Atari Mega Archive 1/Atari Mega Archive - Volume 1.iso/language/gfaxpert.lzh/GFAXPERT.ASC

Text File | 1987-04-22 | 225KB | 5,736 lines

                                Your Second
                               GFA-BASIC 3.0
                                   Manual



                              Second Edition


















                             (c)  Han Kempen
                             Coevorden, 1990










                Everything you always wanted to know about
                  GFA-Basic 3.0, but were afraid to ask

                                   CONTENTS


INTRODUCTION ..........................   7

1. GENERAL
Start-up ..............................   9
Application ...........................   9
Monitor ...............................  10
Break .................................  10
Operating System ......................  10

2. THE EDITOR
Abbreviated Commands ..................  12
Syntax ................................  12
Folded Procedures .....................  13
Tab ...................................  13
Cut and Paste .........................  13
Load ..................................  13
Save ..................................  14
Llist .................................  14
Insert-mode ...........................  15
Direct mode ...........................  15
DEFLIST ...............................  15
Special Characters ....................  16

3. VARIABLES
Variable Type .........................  17
DEFWRD ................................  17
Boolean ...............................  17
Integer ...............................  18
Floating Point ........................  18
VAR ...................................  18
FUNCTION ..............................  19
CLEAR .................................  19
ERASE .................................  19
DUMP ..................................  19
TYPE ..................................  20
READ ..................................  20
SWAP ..................................  20
TIME$ .................................  21
TIMER .................................  21
DATE$ .................................  22

4. MEMORY
RAM ...................................  23
INT{} .................................  23
RESERVE ...............................  23
INLINE ................................  24
MALLOC ................................  25

5. SORT
QSORT v. SSORT ........................  26
QSORT of number-arrays ................  26
QSORT of string-arrays ................  26

6. OPERATORS and NUMERICAL FUNCTIONS
\ .....................................  29
PRED and SUCC .........................  29
MOD ...................................  29
BCLR ..................................  29
BSET ..................................  30
BCHG ..................................  30
LOG ...................................  30
SINQ and COSQ .........................  30
EQV ...................................  31
CARD and SWAP .........................  31
MAX ...................................  31
Correlation ...........................  31

7. STRINGS
INSTR .................................  32
LSET and RSET .........................  32
Parser ................................  32

8. KEYBOARD INPUT
INKEY$ ................................  33
INPUT .................................  34
INPUT$ ................................  35
LINE INPUT ............................  35
KEYTEST ...............................  35
KEYGET ................................  35
KEYLOOK ...............................  36
KEYPRESS ..............................  37
KEYDEF ................................  37
Keyboard ..............................  37
Keyclick, Keyrepeat and CapsLock ......  38

9. SCREEN OUTPUT
PRINT .................................  40
LOCATE ................................  41
PRINT TAB .............................  42
Setscreen (XBIOS 5) ...................  42
Font ..................................  43

10. PRINTER
Printer ready .........................  45
HARDCOPY ..............................  45
Printer-commands ......................  47

11. FILES
Floppy Write Test .....................  50
Step Rate .............................  50
RAM-disk ..............................  50
DIR$() ................................  50
DIR and FILES .........................  51
FSFIRST and FSNEXT ....................  52
EXIST .................................  54
LOF ...................................  54
TOUCH .................................  54
NAME ..................................  54
KILL ..................................  54
File Copy .............................  55
Disk Format ...........................  55
File Allocation Table (FAT) ...........  58
Sectors ...............................  59
Bootsector ............................  61
BLOAD .................................  61
INP and OUT ...........................  62
INPUT and LINE INPUT ..................  62
STORE and RECALL ......................  62
FILESELECT ............................  63

12. MIDI
INPMID$ ...............................  67
INP ...................................  67
Midi-commands .........................  67

13. MODEM
INPAUX$ ...............................  70
INP ...................................  70
Rsconf (XBIOS 15)......................  70

14. MOUSE
Editor ................................  71
Fileselector ..........................  71
MOUSE .................................  71
SETMOUSE ..............................  71
DEFMOUSE ..............................  72

15. JOYSTICK
STRIG and STICK .......................  74

16. SOUND
SOUND and WAVE ........................  75
Dosound (XBIOS 32) ....................  75
Samples ...............................  76
Speech ................................  77
Soundmachine ..........................  77

17. PROGRAM DECISIONS
IF ... ENDIF ..........................  78
SELECT ................................  78

18. PROGRAM LOOPS
Calculations ..........................  79
FOR ... NEXT ..........................  79
Loops .................................  80

19. PROGRAM CONTROL
GOSUB .................................  82
ON BREAK GOSUB ........................  82
ERROR .................................  82
EVERY and AFTER .......................  82
GOTO ..................................  82
DELAY .................................  83
CHAIN .................................  83
EXEC ..................................  83

20. GRAPHICS
SETCOLOR and VSETCOLOR ................  84
Palette ...............................  84
DEFMARK ...............................  87
DEFFILL ...............................  87
DEFLINE ...............................  89
DEFTEXT ...............................  89
GRAPHMODE .............................  90
PLOT and DRAW .........................  91
PCIRCLE ...............................  92
CURVE .................................  92
TEXT ..................................  92
SPRITE ................................  93
VQT_EXTENT ............................  95
Line-A ................................  95
HLINE .................................  96
ACHAR and ATEXT .......................  96
GET and PUT ...........................  96
Degas-Pictures ........................  97
Neochrome-Pictures ....................  98
VSYNC .................................  98
Scroll ................................  98
ACLIP .................................  99
Blitter ...............................  99

21. EVENTS
MENU() ................................ 101
ON MENU BUTTON ........................ 101
ON MENU IBOX .......................... 102

22. PULLDOWN MENU
OPENW 0 ............................... 103
Desk-submenu .......................... 103
File-submenu .......................... 103

23. WINDOWS
GFA-windows ........................... 104
CLOSEW ................................ 104
TITLEW ................................ 105
CLEARW ................................ 105

24. AES-LIBRARY
ALERT ................................. 106
SHEL_GET and SHEL_PUT ................. 106

25. GFAXPERT-FILES
GFAXPERT.DOC .......................... 108
GFAXPERT.LIB .......................... 108
INLINE ................................ 108
STANxxxx.LST .......................... 108
START ................................. 112
small print ........................... 113

EPILOGUE .............................. 114

INDEX ................................. 115


                               INTRODUCTION


Right now you are reading the second edition of the text GFAXPERT.DOC.
This text is not meant to be a replacement of your GFA-manual. On the
contrary, I assume you are already familiar with the GFA-manual and now
want to know everything about GFA-Basic 3.0 that is not described properly
in the manual.

This text is about the (hidden) power of GFA-Basic 3.0. You will find
nothing about version 3.5, apart from this sentence. And this sentence,
because I would like to mention that I don't understand why GFA launched
version 3.5. GFA-Basic is becoming far too expensive.

All remarks in this text, especially about bugs, are based on GFA-Basic
3.07. I still hope version 3.08 will become available (how naive...),
otherwise I'll have to wait for version 4. Not version 4.00 of course,
because I know there will be at least 200 bugs in the first release.

I wrote this text because I was disappointed by the contents of most books
about GFA-Basic 3.0. Some authors use page after page to describe a boring
program. Others delve deeply into menu's, windows and RSC, but ignore the
"regular" Basic-commands. Instead of complaining, I decided to write the
book that I would really like to see myself. Here it is. Forget all other
books about GFA-Basic, you need only two things: your GFA-manual and this
text. And to be honest, perhaps a good book about the AES-library, because
you won't find much about that subject in this text.

In this text you will find quite a few Procedures. Most Procedures that
are listed (or mentioned) in this text can be found in one of the LST-
files in the folder GFAXPERT.LIB. Downloaders should look for the file
GFAXPRT2.ARC.

I strongly advise you to read the chapter 'GFAXPERT-FILES' thoroughly,
before you try to use the Procedure-library GFAXPERT.LIB. Especially note
the following :
     (1) word-variables are the default
     (2) a couple of variables are declared as Standard Globals
     (3) some Standard Functions are defined
     (4) a few Standard Procedures are present
     (5) the Standard Array color.index() is declared
A Procedure could use any of the Standard Globals, Functions, Procedures
or the Standard Array. I usually mention this in comment-lines in the
Procedure. If you Merge such a Procedure into an existing program, you
will have to adapt your program or the Procedure.

I still believe in GFA-Basic 3.0. And I also believe in sharing ideas,
Procedures and programs with other users, starting with you. If you feel
guilty about receiving all these goodies for (almost) nothing, you will
find a free consult in the chapter 'EPILOGUE'.

I could only write this text because many GFA-users shared their
experience with others. I dedicate this text to them. Special thanks to
everyone who pointed out bugs, mistakes and omissions in the first edition
of GFAXPERT.DOC. All mistakes in the second edition are made by


Han Kempen


                               1.  GENERAL


Start-up

Programs in an AUTO-folder are executed automatically after a reset. The
interpreter GFABASIC.PRG is a GEM-program, and cannot be started in this
way. With TOS 1.4 you can install a GEM-program as auto-booting. With
older TOS-versions you could use a program like HEADSTRT.PRG in your AUTO-
folder to start GFABASIC.PRG automatically. You can't start a GFA-program
this way (I think).

If you have written a (compiled) program that can be run either from the
AUTO-folder or from the desktop, you can determine which is the case :
     IF PEEK(&H2C+4)=0        ! 4th byte of Line-F vector
       (...)                  ! AUTO
     ELSE
       (...)                  ! desktop
     ENDIF

There are several ways to (re)start your computer. The obvious one is to
switch the ST off, wait a few seconds (15 seconds with a 1040 ST!), and
switch on again. This is called a "cold" or "hard" reset. Your computer
suffers a little, and it takes some time. If you use the reset-button on
your ST, you perform a "warm" or "soft" reset. The operating system
automatically performs a warm reset if you switch between Low and Medium
resolution on the desktop. If you suspect a program of changing system
variables, you should always use a cold reset. After a warm reset the
system variables in low memory are not initialised again. Garbage will
stay there and will undoubtedly lead to interesting effects. You can
perform both a warm and a cold reset from GFA-Basic with the following
Procedures :
     PROCEDURE coldstart
       SLPOKE &H420,0
       SLPOKE &H426,0         ! probably not necessary
       SLPOKE &H43A,0
       ~XBIOS(38,L:LPEEK(4))
     RETURN
     '
     PROCEDURE warmstart
       ~XBIOS(38,L:LPEEK(4))
     RETURN

If you would like to boot from your second (external) drive B, try :
     SLPOKE &H446,1      ! boot from drive B after next reset
     @warmstart


Application

It is convenient to install the extension GFA as an application for
GFABASIC.PRG. Click once on GFABASIC.PRG and choose Install Application
from the Options-menu. Type GFA as Document Type, click on OK and save the
desktop. If you double-click a GFA-program (extension .GFA) from the
desktop, GFABASIC.PRG is automatically loaded first. Choosing Install
Application you will only see the most recently installed application. Use
a disk-editor to examine the file DESKTOP.INF and you will find all
installed applications (look for #G). You could also use the method
described in the paragraph 'SHEL_GET and SHEL_PUT', or the RECALL-method
from the paragraph 'STORE and RECALL'.


Monitor

The Atari colour monitor SC1224 works with a vertical frequency of either
50 Hz or 60 Hz :
     SPOKE &HFF820A,254       ! 50 Hz
     SPOKE &HFF820A,252       ! 60 Hz
For 60 Hz, bit 1 of the Sync Mode Register is cleared. Don't change bit 0,
or the video controller chip will not use the so-called sync pulses. After
a reset, the operating system defaults to 50 Hz. The screen is a little
larger than at 60 Hz, but the screen flickers slightly. If you connect
your ST to a TV through a modulator, you should use 50 Hz. Otherwise you
are advised to use 60 Hz.


Break

It's not easy to find in the GFA-manual: you can stop a running program by
pressing <Control> <Left Shift> <Alternate> simultaneously. But if you're
reading this text, you know this already. It's impossible to interrupt a
program during DELAY! Study the Standard Procedure Break in one of the
STANxxxx.LST-files to see how I react after a 'Break'.


Operating System

If you program in a language like GFA-Basic, you won't notice much of the
actual workhorse inside your ST-computer: The Operating System (TOS). But
even GFA-Basic does not have a Basic equivalent for all TOS-functions,
although you can use almost all functions from GFA-Basic.

TOS can be divided in two main parts: (GEM)DOS and GEM. The first is a
collection of "lower level" routines for communication with keyboard,
screen, printer, etc. In GFA-Basic you can call these routines with the
commands BIOS, XBIOS and GEMDOS. The Graphics Environment Manager (GEM)
consists of two collections of routines: the VDI (Virtual Device
Interface) and the AES (Application Environment Services). The VDI takes
care of regular graphics and should have included GDOS. Atari didn't
include GDOS in the VDI, so you have to load it if you need it. Most VDI-
functions have a Basic equivalent in GFA. The AES takes care of the
communication with the user through menu, Alert-box, window, etc. Most
AES-functions can be accessed through the AES-library in GFA-Basic 3.0.

With GEMDOS-function 48 (Sversion) you can find the version of your
GEMDOS. For both the old TOS and the Blitter-TOS &H1300 (version 0.19) is
returned. The French Turbo-DOS has version 0.20 and the new Rainbow TOS of
1988 has version 0.21.
Another way to find out the version of TOS uses the system header of TOS
(not necessarily located in ROM!) :
     adr%=LPEEK(&H4F2)
     version$=HEX$(DPEEK(adr%+2))
The good old ROM-TOS (1986, actually not so good) has version &H0100
(1.0), the Mega-ST Blitter-TOS (1987) version &H0102 (1.2). And of course
the new TOS ('Rainbow TOS') has version 1.4. You could also examine the
date of your TOS-version :
     date$=HEX$(LPEEK(adr%+24))
My ancient TOS 1.0 has '11201985' as the date.


                              2.  THE EDITOR


Abbreviated Commands

The editor recognizes the following abbreviations (not a complete list) :

ALINE     - ALI          FILESELECT- FILE         POLYMARK  - POLYM
ARECT     - AR           FILL      - FI           PRINT     - P or ?
ARRAYFILL - ARR          FUNCTION  - FU           PROCEDURE - PRO
ATEXT     - AT           GOSUB     - G or @       PSET      - PS
BMOVE     - B            GRAPHMODE - GRA          QUIT      - Q
BOUNDARY  - BOU          HIDEM     - HI           REPEAT    - REP
CASE      - CA           HLINE     - HL           RESTORE   - RES
CIRCLE    - CI           IF        - I            RETURN    - RET
CLOSE     - CL           INPUT     - INP          RSET      - RS
COLOR     - C            LINE      - LI           SELECT    - S
DATA      - D            LINE INPUT- LI           SETCOLOR  - SET
DEFFILL   - DEFF         LOCAL     - LOC          SETMOUSE  - SETM
DEFLINE   - DE           LOOP      - L            SGET      - SG
DEFMARK   - DEFMA        LPRINT    - LPR          SHOWM     - SH
DEFMOUSE  - DEFM         LSET      - LS           SWAP      - SW
DEFTEXT   - DEFT         MID$(..)= - MI ..)=      TEXT      - T
DELETE    - DEL          MOUSE     - MOU          UNTIL     - U
DRAW      - DR           NEXT      - N            VOID      - V
EDIT      - ED           OPEN      - O            VSYNC     - VS
ELLIPSE   - ELL          PAUSE     - PA           WAVE      - WA
ELSE      - E            PBOX      - PB           WEND      - WE
ENDFUNC   - ENDF         PCIRCLE   - PC           WHILE     - W
ENDIF     - EN           PELLIPSE  - PE
ENDSELECT - ENDS         PLOT      - PL
ERASE     - ERA          POLYFILL  - POLYF
EXIT IF   - EX           POLYLINE  - POL

If the abbreviated command is followed by anything else, you have to
insert a space (e.g. 'C 1'), except with '@' and '?' :
     @proc1
     G proc1
     '
     ?"hello"
     P "hello"


Syntax

The parser checks for correct syntax after you press <Return>. Many typo-
bugs are prevented this way. The only disadvantage is that the parser
recognizes some variables as commands. It's impossible to use the follo-
wing names as the first word on a line: data_byte|, dirty$, double,
printer$, file%, quit!. The last one is nasty, because the parser changes
the line 'quit!=FALSE' into 'QUIT!=FALSE' without warning for a syntax-
error. If you now run the program you will return to the desktop when QUIT
is encountered. Of course you have not lost your valuable program, because
you always Save before you Run. Do you really? If the parser refuses the
name of a variable, you can use LET (e.g. 'LET quit!=FALSE'). But you will
have to change the name if it is a label (e.g. the label 'data1:' could be
changed into '1data:' or 'd.ata1:').


Folded Procedures

If you press <Control> <Help> on a Procedure-line, all Procedures follo-
wing and including the current one are folded/unfolded. You can unfold all
Procedures at once by putting the cursor on the first Procedure-line and
pressing <Control> <Help>. I suggest you leave all Procedures in the
Procedure-Library GFAXPERT.LIB folded, unless you want to examine a
Procedure. The editor-commands 'Find' and 'Replace' will skip folded
Procedures. Never change the Procedure-line of a folded Procedure, always
unfold it first.


Tab

If you press <Tab>, the cursor jumps to the next tab-position, without
altering the current line. If you use <Left Shift> <Tab>, the line is
filled with spaces from the current cursor-position to the next tab-
position. Pressing <Right Shift> <Tab> erases all consecutive spaces to
the left of the current cursor-postition. If the current cursor-position
happens to be a space, this space and all spaces to the right are erased
as well.


Cut and Paste

If you press <Control> <P>, the current line from the cursor to the end of
the line is cut, and saved in an internal buffer. <Control> <O> inserts
the saved line at the current cursor-position. You can use this method to
"cut and paste" a part of a line. Press <Control> <P>, then <Control> <O>
to restore the original line. Move the cursor to the desired position and
press <Control> <O>. Block-operations are only possible with complete
lines.


Load

You can use Load only with *.GFA-files, not with ASCII-files (such as the
*.LST-files). ST-Basic files are ASCII-files, so you can Merge them.

More recent programs in GFA-Basic (from 3.04) cannot be loaded by earlier
interpreters (up to 3.02). Of course you should have the most current
version (at least version 3.07), but the following method should always
work. Lengthen the program until you can load it successfully :
     OPEN "A",#1,file$
     PRINT #1,STRING$(1000,0)
     CLOSE #1


Save

After 'Save' (*.GFA-file) or 'Save,A' (*.LST-file) with an existing file,
the old file is renamed with a BAK-extension. Nice precaution, but you
should delete those *.BAK-files every now and then.

If you kill and save files regularly, new files will be stored in a
fragmented way. Loading a fragmented file takes more time than loading a
file that occupies consecutive sectors on the disk. You can correct this
as follows. First make a backup-disk (yes, you should already have one).
Copy all files to a RAM-disk by clicking on the drive-icon and dragging it
to the window of the destination drive. You can't use disk-copy (dragging
drive-icon to drive-icon) because the destination-drive is a RAM-disk.
Format the source-disk and copy all files back (this must be a file-copy,
not a disk-copy). Now, all files are saved on consecutive sectors. You
could speed up things a little bit more by copying the most-used files
first. The drive-head now needs less time to reach these files.

Don't try to 'Save,A' an existing file to a full disk. I have tried it
once and lost both the original file (should have become a *.BAK-file) and
of course the saved file. Also, the editor (or TOS) had erased the program
from memory... Thank you.


Llist

There has been some confusion about the following point-commands for the
printer :
     .p-       - point-commands are not printed
     .p+       - point-commands are printed again
     .llxx     - line-width
     .plxx     - page-length
     .pa       - form feed
Sometimes the commands '.cp' and '.nu' are mentioned, but I don't know how
to use these.

You can only use one point-command in one line. I use the following lines
for my printer (96 characters/line in Elite-mode) :
     .p-
     .n4
     .lr3
     .ll88
Save this as LLIST.LST and Merge it after the last line of a program
before choosing 'Llist'. The actual listing is then printed with 80
characters/line, preceded by the line-numbers (4 characters + space). If
your program is longer than 10000 lines, you should use '.n5', but in that
case you probably don't have time to read this. A nice touch is the
automatic execution of a form feed after printing the listing.

If the listing contains special characters (ASCII-code < 32 or > 126),
some of those characters might be interpreted as printer-commands. My
printer switches to condensed printing after receiving the Atari-symbol.
Installing the proper printer-driver (e.g. PTEPSON.PRG) will prevent that.
But I never install a printer-driver because there are some serious
disadvantages. Read more about it in the paragraph 'HARDCOPY'.

You can stop the printing process by pressing the 'Break'-combination
<Control> <Left Shift> <Alternate>, unless Break has been disabled with
'ON BREAK CONT'. Your printer will continue printing though, until its
input-buffer is empty, or until you turn the printer off.


Insert-mode

If you return to the editor, you'll always be in Insert-mode, even if you
left the editor in Overwrite-mode. By the way, the editor restores the
original colour-palette, so you are not bothered by palette-changes in a
program. In the old days I was sometimes caught by the dreaded phenomenon
of black characters on a black background, but now you can always read the
listing on your screen.

By the second way, there is only one thing I don't like about the GFA-
editor. It's not easy to merge a Procedure from a LST-file with the
program you're working on. Save the program, clear memory with 'New',
'Merge' the LST-file, mark the Procedure as a block, save the block,
'Load' the original program, find the correct line and 'Merge' the saved
block. A new command NMerge (New+Merge) would make the life of a GFA-
programmer a little easier. A better idea would be the command BMerge
(Block-Merge). Then I could choose this command, clip a Procedure-block,
and the block would be inserted in the listing automatically. Are you
reading this, Frank? If you are, how about a function for changing upper
case into lower case. In the GFA-EDITOR I SOMETIMES (oops) forget I
pressed CapsLock. And how about a function to clear a line from the cursor
to the next space-character. And...


Direct Mode

Enter the Direct Mode by pressing <Esc> or <Shift> <F9> in the editor.

In Direct Mode you can restore the previously used line with <Undo>. With
<Up arrow> and <Down arrow> you can even recall up to 8 of the last used
lines. Press <Insert> to switch between Insert-mode and Overwrite-mode. As
usual <Esc> clears the line, but if you press <Esc> on an empty line, you
will return to the editor immediately. You can also return to the editor
with <Control> <Shift> <Alternate>, even without first clearing the
command-line. You can call Procedures in your program from the Direct Mode
(e.g. '@show'). If you (temporarily) merge some special Procedures with
the program you are developing, you could use the Direct Mode as a Command
Line Interpreter.


DEFLIST

The command 'DEFLIST n' only works in Direct Mode, not in a program. You
can also choose 'Deflist' from the drop-down menu, after clicking on the
Atari-symbol.
Special Characters

You can enter characters with ASCII-code 32-126 directly from the key-
board. These characters are usually called ASCII-characters. The codes
0-31 and 127 are used as control-codes, but additionally special charac-
ters have been assigned to these codes. The characters with code 128-255
are sometimes called "extended ASCII-characters" and are partly identical
to the IBM-characters with the same codes. I loosely use the expression
"ASCII-code" for all codes 0-255.

You can enter characters with code 0-31 or 127-255 by pressing <Alternate>
and then entering the character code. Release the <Alternate>-key and the
character appears on your screen. E.g., you could enter the Escape-
character by holding <Alternate> down and pressing <2> and <7>. This is
much faster than entering CHR$(27), but Llisting a file with Escape-
characters is probably not a good idea (less important, 1st Word Plus
could get confused too). Llisting CHR$(27) doesn't bother your printer at
all. It's not possible to enter CHR$(10) or CHR$(13) with the 'Alternate'-
way. You can enter the first by pressing <Control> <A> and then <1> <0>
<Return>. For code 13 you have to use CHR$(13).

Never use code 4 (EOT, visible as left arrow) in a LST-file. If you Merge
a LST-file, the GFA-editor thinks the end of the file is reached at that
point (&H04) and refuses to load anything following this code!


                              3.  VARIABLES


Variable-type

In GFA-Basic we use the expressions 'Byte', 'Word' and 'Integer' for the
three integer-variables. Because all three are integers, the expression
'Integer' for the 4-byte integer-variable is sligthly confusing. In other
languages this variable is called 'Longword' or simply 'Long'. An address
in RAM should always be a 4-byte integer.


DEFWRD

I prefer to declare word-variables as the default (for variables without
postfix) with: DEFWRD "a-z"

I recommend the use of word-variables (2 bytes) for two reasons. In
calculations, the use of the special integer-operators (ADD, SUB, INC,
etc.) speeds the program up considerably. If you insist on using the
regular operators (+, -, etc.) you should use floating point variables
instead. Using the regular operators, the interpreter has to convert
integer-variables to floating point, does the calculation and converts the
result back to integer again. That's why a#*b# is calculated faster than
a&*b&. But MUL(a&,b&) is much faster than a#*b#. It takes some time to
recognize what an expression like DIV(a,MUL(ADD(a,b),SUB(b,c))) means. I
suggest you use the regular operators if the calculation-time is not
critical. In loops, the gain in calculation time really counts, so you
should use the integer-operators. That way you will learn Polish too. The
second reason for using word-variables is, that in a compiled program
calculations with word-integers are usually the fastest.

IMPORTANT: if a number-variable has no postfix in this text, you should
assume it's a word-variable. I'll use the postfix |, % or # where
appropriate. Please note that the interpreter assumes a number-variable
without postfix is a floating point variable, unless you use DEFWRD "a-z".


Boolean

The following five lines :
     IF number>0
       test!=TRUE
     ELSE
       test!=FALSE
     ENDIF
can be shortened to just one line :
     test!=(number>0)
This works, because the '>'-operator returns TRUE or FALSE (actually -1
or 0).

Another little trick :
     IF i=1
       n=n*2
     ELSE IF i=2
       n=n*5
     ELSE
       n=0
     ENDIF
This could be shortened to :
     n = n*-2*(i=1) + n*-5*(i=2)
The example is ridiculous, but the principle involved could be useful. The
expressions 'i=1' and 'i=2' are either 0 (FALSE) or -1 (TRUE).

It is not necessary to use something like :
     IF flag!=TRUE
       (...)
     ENDIF
You can simply use :
     IF flag!
       (...)
     ENDIF


Integer

You can't assign 2^31 to a 4-byte integer-variable. Although an integer
contains 32 bits, you can't use bit 31. This bit is a flag for a negative
integer. The largest positive number you can assign to an integer-variable
is therefore 2^31-1 (2147483647). I could have written an analogue
paragraph about the 2-byte word-variables, but I didn't.


Floating Point

The range of floating point variables (postfix #) is :
     -1.0E1000 < x# < 1.0E1000
Larger or smaller numbers can be used in calculations, but not printed,
because the exponent may contain not more than 3 digits (1.0E1000 is
displayed as 1.0E;00).


VAR

If you call a Procedure and use VAR (call by reference), all variables
and/or arrays after VAR are called by reference. An example to clarify
this :
     @test(10,5,number%,array%())
     (...)
     PROCEDURE test(a,b,VAR x%,y%())
       ' now a=10 and b=5 (call by value)
       ' number% and array%() can now be used as x% and y%()
       x%=a+b                 ! global variable number% is now 15
       ARRAYFILL y%(),1       ! all elements of array%() are now 1
     RETURN
In prehistoric days you could have used SWAP, but VAR makes life easier :
     @test(*a%())
     (...)
     PROCEDURE test(ptr%)
       SWAP *ptr%,x%()        ! array a%() temporarily renamed as x%()
       (...)                  ! do something with the array
       SWAP *ptr%,x%()        ! restore pointer before leaving Procedure
     RETURN


FUNCTION

You can only leave a FUNCTION by RETURNing a value or a string. This
value/string is usually assigned to a variable. If the FUNCTION returns a
string, the function-name has to end with '$' :
     FUNCTION test
       RETURN 126
     ENDFUNC
     '
     FUNCTION test$
       RETURN "this is a string"
     ENDFUNC


CLEAR

Because CLEAR is automatically executed when you run a program, it's not
necessary to start you program with this command.


ERASE

It's impossible to reDIMension an existing array. You first have to ERASE
the existing array and then you can DIMension a new array. It is not
necessary to test for the existence of an array with DIM?() before you use
ERASE. In other words, you can use ERASE even if the array doesn't exist :
     ERASE array$()      ! just in case this array already exists
     DIM array$(200)

After ERASEing an array, GFA rearranges the remaining arrays. All arrays
that have been DIMensioned after the deleted array are moved in order to
fill the gap of the deleted array. This is important if you use V:array(0)
in your program (read the paragraph 'RESERVE').


DUMP

Examine all variables in your program by typing 'DUMP' in Direct Mode.
Press <CapsLock> to slow down the scrolling-speed, or press the right
<Shift>-key to temporarily stop the scrolling. The Procedure Debug enables
you to use DUMP during debugging. This is the best way to discover those
nasty typo-bugs in a variable-name. You'll probably be surprised to see
the names of deleted variables as well. Also, any variable-name you used
in Direct Mode appears. All these names are SAVEd with the program! Delete
all unwanted names as follows (a RAM-disk would be convenient) :
     - Load the file
     - Save,A (press <Return> in Fileselector)
     - New
     - Merge (press <Return> again)
     - Save (press <Return> once more)
The file could be much shorter after this operation.


TYPE

The command TYPE does not seem to work properly if you use local
variables. I don't know what's wrong.


READ

As a rule, I always RESTORE the appropriate label before READing DATA-
lines. That way I can use DATA-lines in Procedures :
     PROCEDURE read.data
       RESTORE these.data
       (...)                  ! READ the DATA here
       these.data:
       DATA 1,2,3,4
     RETURN


SWAP

The 52 cards in bridge (or another card-game) can be represented by a
byte-array. Fill the elements 1-52 of the array with the value 1-52. The
values 1-13 would represent the Club-cards (2,3,4,...,Q,K,A), values
14-26 the Diamonds, values 27-39 the Hearts and values 40-52 the Spades.
Shuffling the cards can now be simulated with the Procedure Shuffle :
     DIM deck|(52)
     FOR i=1 TO 52       ! ignore index 0
       deck|(i)=i
     NEXT i
     @shuffle(deck|())
     (...)
     PROCEDURE shuffle(VAR proc|())
       LOCAL i,j
       FOR i=DIM?(proc|())-1 DOWNTO 2
         j=RAND(i)+1
         SWAP proc|(j),proc|(i)
       NEXT i
     RETURN


TIME$

You can use TIME$ to print the current time on the screen. In the
Procedure Time you'll find a way to print the time every second, although
TIME$ is updated every two seconds :
     PROCEDURE time
       ' *** activate with : EVERY 200 GOSUB time
       ' *** global :  TIMER$
       LOCAL t$
       t$=TIME$
       IF t$=timer$
         MID$(timer$,8)=SUCC(RIGHT$(timer$))
       ELSE
         timer$=t$
       ENDIF
       PRINT AT(1,1);timer$
     RETURN


TIMER

If you need a stopwatch, you can use the following Procedures :
     PROCEDURE stopwatch
       ' *** global :  STOP.SECONDS#  STOP.H  STOP.M  STOP.S  WATCH.ON!
       LOCAL s#
       IF watch.on!
         stop.watch#=TIMER
         stop.seconds#=(stop.watch#-start.watch#)/200
         stop.h=stop.seconds#/3600
         s#=stop.seconds#-stop.h*3600
         stop.m=s#/60
         stop.s=s#-stop.m*60
         watch.on!=FALSE
       ELSE
         watch.on!=TRUE
         start.watch#=TIMER
       ENDIF
     RETURN
     '
     PROCEDURE print.stopwatch
       IF stop.h>0
         PRINT stop.h;" h ";stop.m;" m";
       ELSE
         IF stop.m>0
           PRINT stop.m;" m ";stop.s;" s";
         ELSE
           IF stop.seconds#>=10
             PRINT USING "##.# s",stop.seconds#;
           ELSE
             PRINT USING "#.## s",stop.seconds#;
           ENDIF
         ENDIF
       ENDIF
     RETURN
You start the stopwatch by calling the Procedure Stopwatch. Calling this
Procedure again will stop the stopwatch. Then you can PRINT the elapsed
time at the current cursor-position with the Procedure Print.stopwatch, or
you could use one of the Global Variables from the Procedure Stopwatch to
do something else.


DATE$

Find the day of the week with the Procedure Day.of.week :
     PROCEDURE day.of.week(day.date$,VAR day$)
       LOCAL day,mp,month,year,m,h,w,week$,n
       day=VAL(LEFT$(day.date$,2))
       mp=INSTR(day.date$,".")
       month=VAL(MID$(day.date$,mp+1,2))
       year=VAL(RIGHT$(day.date$,4))
       IF month<=2
         m=10+month
         year=year-1
       ELSE
         m=month-2
       ENDIF
       h=year/100
       y=year-100*h
       w=(TRUNC(2.6*m-0.2)+day+y+TRUNC(y/4)+TRUNC(h/4)-2*h) MOD 7
       RESTORE weekdays
       FOR n=0 TO w
         READ day$
       NEXT n
       '
       weekdays:
       DATA Sunday,Monday,Tuesday,Wednesday,Thursday,Friday,Saturday
     RETURN
This Procedure uses Zeller's Congruence to determine the day of the week.


                                4.  MEMORY


RAM

An overview of the memory of my 1040 ST (start at the bottom) :
                     address
                    &H FFFFF   top of memory of 1040 ST (1024 K)
                    &H FFD00   767 unused (?) bytes
       XBIOS(2)   = &H F8000   screen memory (32000 bytes)
       HIMEM      = &H F4000   16384 unused bytes (MALLOC(-1))
                    &H .....   free memory (length FRE(0) bytes)
                    &H 388EA   program + variables (length varies)
                    &H 10C2E   GFA-Basic 3.07 interpreter
       BASEPAGE   = &H 10B2E   Basepage GFA-Basic (256 bytes)
                    &H  A100   start of available RAM
                    &H  6100   global AES-variables
                    &H  29B4   global BIOS- and GEMDOS-variables
       L~A        = &H  293A   Line A variables
                    &H   93A   local BIOS-variables + BIOS-stack
                    &H   400   BIOS system-variables
                    &H     0   exception vectors

The BIOS system-variables (&H400 - &H4FF) are "cast in concrete" by Atari.
Other (undocumented) variables in RAM should be avoided.


INT{}

You can use either INT{adr%} or WORD{adr%}. As you know, w=WORD{adr%} is
faster than w=DPEEK(adr%), but you can't use WORD{} and the other related
commands in supervisor mode. This means you can't access memory below
address &H800. Of course you can PEEK/DPEEK/LPEEK everywhere (DPEEK and
LPEEK on even addresses only), and you can use SPOKE/SDPOKE/SLPOKE to
write in supervisor mode.


RESERVE

The command RESERVE can be used in three different ways :
     RESERVE  n% : reserve n% bytes for GFA-Basic, release RAM up to HIMEM
     RESERVE -n% : reserve last n% bytes of RAM up to HIMEM
     RESERVE     : restore to original
The second command is my favourite. You must use a multiple of 256 with
RESERVE. After 'RESERVE -400', only 256 bytes are released to GEMDOS. In
this case you would have to use 'RESERVE -512', although you need only 400
bytes! Use the Function Multiple if arithmetic is not your strongest
point :
     RESERVE -@multiple(n%,256)
Use 'RESERVE -n%' only once in your program. If you RESERVE memory a
second time with 'RESERVE -m%', GFA releases m% bytes, not n%+m%.

The command RESERVE (restore) does not always function properly. Especial-
ly after EXEC 3 it's often impossible to restore the memory. I suspect
this has something to do with the use of the malloc-function by the
operating system. You could try the following :
     RESERVE -n%         ! reserve as much as needed (multiple of 256)
     base%=EXEC(3,...)   ! load, but don't start
     (...)
     ~MFREE(HIMEM)       ! memory above GFA-Basic
     ~MFREE(base%)       ! memory from Basepage of loaded program
     RESERVE             ! hope it works now
Don't be surprised by hang-ups or bombs after this operation...

There are several ways to reserve a part of memory for special purposes
such as music, pictures or other programs. E.g., you could use a string-
variable to store a complete screen or a GET-picture. Don't use strings if
garbage collection is a serious risk. If a large array is declared, the
interpreter sometimes moves the strings in memory to create space for the
new array. If you assign a new string to an existing string-variable, the
old string is not erased. During garbage collection all unused strings are
deleted and the active strings are rearranged. This means the address of a
string (accessed through VARPTR or V:) is not fixed. That's not important
for a GET-picture, because 'PUT x,y,pic$' still works all right. But if
you swap screens with ~XBIOS(5,L:adr%,-1,-1), or call a routine with
~C:adr%(...), garbage collection will be fatal. One solution is not to use
a variable for the address, but to use VARPTR or V:. A different approach
would be the use of a byte-array :
     OPEN "I",#1,file$
     LET bytes%=LOF(#1)            ! how much space is needed?
     CLOSE #1
     DIM assembler|(bytes%-1)      ! create space for assembler-routine
     adr%=V:assembler|(0)
     BLOAD file$,adr%              ! load the routine
You can use the variable adr% safely, because a garbage collection has no
influence on arrays. However, after ERASEing an array, all arrays that
have been DIMensioned after the deleted array are moved in memory. So the
array-method is not reliable either, unless you are certain that ERASE
will not be used after you have determined the address of the byte-array.
Another solution would be to declare the byte-array early in your program,
so it will not be moved after ERASE. The only complete safe way is the use
of INLINE or MALLOC.


INLINE

Use D (=DUMP) to dump an Inline-file in Hex-code to the printer.

Don't use 'Save,A', because you will lose the Inline-code. You can't use
INLINE in LST-files. If you would like to use INLINE in combination with a
LST-file you could proceed as follows. First, create an INLINE-folder in
the main directory and SAVE the Inline-code as a file (extension INL) in
this folder. Merge the LST-file in your program and load the Inline-code
in the INLINE-line. The program should be saved with 'Save'.

The only limitation with INLINE is the maximum length of 32746 bytes. If
you need more space, you have to use MALLOC.

If you change the length of an existing INLINE-line, the editor sometimes
erases a few lines from your program. It's safer to completely delete the
old INLINE-line and then enter the new INLINE-line.


MALLOC

This is how you could use MALLOC :
     unused%=MALLOC(-1)  ! "unused" memory above HIMEM (used by GEM)
     RESERVE -n%         ! release last n% bytes to GEMDOS
     max%=MALLOC(-1)
     IF max%<>0
       adr%=MALLOC(max%-unused%)  ! n% bytes now available to GFA-Basic
     ELSE
       ' error
     ENDIF
     (...)               ! do something interesting
     ~MFREE(adr%)        ! give back to GEMDOS...
     RESERVE             ! and back to GFA-Basic
Atari recommends you leave at least 8K to GEM, so you can't go wrong if
you leave 16384 bytes to GEM (see paragraph 'RAM').

Do not use MALLOC to allocate a lot of small memory-blocks, as GEMDOS will
get confused. This problem is related to the "40-folder limit", because
MALLOC uses the same buffer that is used to store information about a
folder (see paragraph 'FILESELECT'). Allocate one large area and split it
up in as many parts as you need. Also consider the use of INLINE, strings
or byte-arrays instead of using MALLOC (read the paragraph 'RESERVE'). Do
not use MALLOC in an accessory, or the allocated memory may be lost if the
user changes the resolution.

MALLOC(-1) returns the size of the largest available memory-block. Expect
problems if another program has allocated a couple of separate memory-
blocks to GEMDOS. In that case you would have to use MALLOC(-1) again,
until a returned value of '0' indicates there are no more memory-blocks
available.


                                 5.  SORT


QSORT v. SSORT

QSORT is faster than SSORT, unless the array is almost sorted already. I
understand QSORT uses the recursive Quick-sort method, so you need more
memory than with SSORT (iterative Shell-sort). Sort-freaks can study the
Procedures Quick.sort.int and Shell.sort.int to see how the Quick-sort and
Shell-sort can be implemented with ordinary GFA-Basic commands (like that
dance: Quick, Shell, slow).


QSORT of number-arrays

Number-arrays can be QSORTed in three different ways :
     QSORT x%()          - sorts array ; also with x|(), x&() or x#()
     QSORT x%(),n        - sorts elements 0 through n-1
     QSORT x%(),n,y%()   - elements of y%() are swapped too
In all cases x%(-1) results in sorting in decreasing order.

The third method is interesting if you need a sorted output, but don't
want to change the original array. You can accomplish this as follows :
     - copy x%() to temporary array temp%()
     - determine index of last element : last=DIM?(temp%())-1
     - create index array : DIM index%(last)
     - fill index-array with index 0 through last
     - sort array : QSORT temp%(),last+1,index%()
     - ERASE temp%()
The index-array must be an integer-array (postfix %). Also, the number of
elements is not optional if you sort with an index-array. You can now
print the numbers in array x%() in increasing order :
     FOR i=0 TO last
       PRINT x%(index%(i))
     NEXT i

I have never seen the correct syntax for QSORT in print, so here it is :
     QSORT x([s])[,n[,y%()]]


QSORT of string-arrays

A string-array can be sorted in the same three ways as described for
number-arrays. If you have created an index-array with last_name$(), you
could print an alphabetical list :
     FOR i=0 TO last
       PRINT first_name$(index%(i))'last_name$(index%(i))
     NEXT i

There are two extra possibilities with string-arrays.


For the first possibility, create a byte-array and fill with appropriate
ASCII-values :
     DIM ascii|(255)
     ARRAYFILL ascii|(),32    ! CHR$(32) is the space-character
     FOR i=48 TO 57
       ascii|(i)=i            ! 0 - 9
     NEXT i
     FOR i=65 TO 90
       ascii|(i)=i            ! A - Z
     NEXT i
     FOR i=97 TO 122
       ascii|(i)=SUB(i,32)    ! a - z converted to A - Z
     NEXT i
All characters that are not numbers or letters will be treated as a space
(ASCII-value 32). Use the array ascii|() for sorting a string-array :
     QSORT x$() WITH ascii|()
Now 'Atari' and 'ATARI' are treated exactly the same, because the
interpreter uses the array ascii|() to convert lower case letters tempora-
rily to upper case before sorting. You can even treat the international
characters (ASCII-values > 127) correctly, e.g. ascii|(129)=85. Use a few
DATA-lines to add the correct ASCII-value, like this :
     DATA 128,67,129,85,130,69
You can combine this method with an index-array as well. The correct
syntax is :
     QSORT x$([s]) WITH b|() [,n[y%()]]
If you have done your homework, you should now be able to write a clever
alphabetical sorting-program yourself. You wanted to become an expert,
didn't you? Compare your program with the Procedures Ascii.qsort and
String.index.qsort :
     PROCEDURE ascii.qsort(VAR txt$())
       IF DIM?(ascii|())=0
         @initio.ascii.array
       ENDIF
       QSORT txt$() WITH ascii|()
     RETURN
     '
     PROCEDURE initio.ascii.array
       LOCAL i,code1,code2
       DIM ascii|(255)
       ARRAYFILL ascii(),32           ! fill with space-character
       FOR i=48 TO 57
         ascii|(i)=i                  ! 0 - 9
       NEXT i
       FOR i=65 TO 90
         ascii|(i)=i                  ! A - Z
       NEXT i
       FOR i=97 TO 122
         ascii|(i)=SUB(i,32)          ! a - z, converted to A - Z
       NEXT i
       RESTORE ascii.data
       REPEAT
         READ code1,code2
         ascii|(code1)=code2
       UNTIL code1=0
       '
       ascii.data:
       ' *** format : ASCII-code,replacement
       DATA 128,67,129,85,130,69,131,65,132,65,133,65,134,65,135,67
       DATA 136,69,137,69,138,69,139,73,140,73,141,73,142,65,143,65
       DATA 144,69,145,65,146,65,147,79,148,79,149,79,150,85,151,85
       DATA 152,121,153,79,154,85,155,67,158,83,160,65,161,73,162,79
       DATA 163,85,164,78,165,78,166,65,167,79,176,65,177,79,178,79
       DATA 179,79,180,79,181,79,182,65,183,65,184,79,192,121,193,121
       DATA 225,83,0,0
     RETURN
     '
     PROCEDURE string.index.qsort(switch!,VAR txt$(),index%())
       ' *** the index-array has to exist already
       ' *** if switch!=TRUE, array ascii|() is used
       LOCAL last,i
       last=DIM?(txt$())-1           ! index of last element
       DIM temp$(last)
       FOR i=0 TO last
         temp$(i)=txt$(i)
       NEXT i
       FOR i=0 TO last
         index%(i)=i
       NEXT i
       IF switch!
         IF DIM?(ascii|())=0
           @initio.ascii.array
         ENDIF
         QSORT temp$() WITH ascii|(),last+1,index%()
       ELSE
         QSORT temp$(),last+1,index%()
       ENDIF
       ERASE temp$()
     RETURN

The second extra possibility with string-arrays is the use of 'OFFSET o'
to ignore the first 'o' characters during sorting. Suppose you have
created an array files$() with FILES and would like to sort the files by
length :
     QSORT files$() OFFSET 13,n
The first character (either a space or '*') and the filename (the next 12
characters) are now ignored during sorting.


                  6.  OPERATORS and NUMERICAL FUNCTIONS


\

The operator '\' (backslash) is identical to DIV :
     a=b\c
Integer-division is not as useful as the other integer-operations, because
the result is an integer. Of course it is, but this can easily result in
large rounding errors.


PRED and SUCC

PRED(i) is faster than i-1 and SUCC(i) is faster than i+1. Both functions
can also be used with strings. Note the clever use (ahem) of SUCC in the
following line from the Procedure Time :
     MID$(timer$,8)=SUCC(RIGHT$(timer$))
The rightmost digit of timer$ (always even) is increased with one.


MOD

If you use a counter in a loop in order to do something every time the
counter reaches a multiple of 10, you could do this as follows :
     IF counter MOD 10=0      ! multiple of 10?
       (...)                  ! yes, do something
     ENDIF
You could also use :
     IF MOD(counter,10)=0
       (...)
     ENDIF


BCLR

In GFA-Basic version 2.x you used AND to clear a bit :
     x|=x| AND &X11111011     ! clear bit 2 of this byte
Remember, the first (rightmost) bit is bit 0, so a byte contains bit 0-7
from right to left. In GFA-Basic 3.0 you clear a bit simply with :
     x|=BCLR(x|,2)            ! clear bit 2 of this byte
But if you want to clear more than one bit, you should use the AND-method:
     x|=x| AND &X11110000     ! clear bit 0-3 of this byte
In this case you use a so-called mask to clear certain bits. You can use
AND also as a function :
     y|=AND(x|,&X11110000)    ! even faster than previous example
This way you can test if a bit-mask "fits" a variable :
     IF AND(x|,mask|)
       (...)
     ENDIF
An example of this method :
     IF AND(BIOS(11,-1),&X1001)
       (...)             ! user pressed <Alternate> + right <Shift>
     ENDIF
BSET

In GFA-Basic 2.x you needed OR to set a bit, but now you use BSET :
     x|=BSET(x|,1)
You still need the OR-method if you want to set more than one bit fast :
     x|=x| OR &X1010          ! set bit 1 and 3
The mask &X1010 is used to set bits 1 and 3. Compare this with the AND-
method, where 0 is used to clear a bit, while here 1 is used to set a bit.
You can use OR not only as an operator, but also as a function :
     y|=OR(x|,&X1010)


BCHG

Instead of BCHG you should use the XOR-method if you want to change more
than one bit (with a mask) :
     x|=x| XOR &X1110         ! change bit 1-3
XOR can be used as a function as well.


LOG

Logarithms with a base other than 10 or e are computed as follows :
     LOG(x)/LOG(base)


SINQ and COSQ

If you are going to convert SIN (or COS) into SINQ (COSQ), you'll have to
change from radials to degrees. For example, you would convert SIN(x) to
SINQ(DEG(x)). Although SINQ is about five times faster than SIN, this
extra computation makes the difference a little less spectacular. If you
are lucky, the variable already is in degrees, so you can use SINQ
immediately. SINQ and COSQ should not be used if you need very accurate
results, only if you plot the result and are not going to use it for
further computations. Examine the difference between the use of SIN/COS
and SINQ/COSQ to see if the less accurate result is acceptable. In High
resolution try something like this :
     fac#2*PI/639
     DRAW 0,200
     FOR x=0 TO 639
       y#=SIN(x*fac#)
       DRAW TO x,200+y#*200
     NEXT x
     ~INP(2)
     CLS
     '
     DRAW 0,200
     FOR x=0 TO 639
       y#=SINQ(DEG(x*fac#))
       DRAW TO x,200+y#*200
     NEXT x
     ~INP(2)
     CLS
     '
     fac#=360/639
     DRAW 0,200
     FOR x=0 TO 639
       y#=SINQ(x*fac#)
       DRAW TO x,200+y#*200
     NEXT x
     ~INP(2)


EQV

EQV doesn't work properly. EQV(0,-1) should be 0, but equals -65536. The
bits 16-31 are always set: EQV seems to look at the bits 0-15 only.


CARD and SWAP

If a 4-byte integer (postfix %) consists of two words, you can extract
these with :
     low.word=CARD(x%)
     high.word=CARD(SWAP(x%))
Both words are interpreted as positive numbers.

Unfortunately, there is no analogue function to swap the low and high
byte of a word. That would be useful if you want to convert a word
into/from Intel-format (MS-DOS). Rotating 8 bits should do the trick :
     FUNCTION intel.word(x%)
       RETURN CARD(ROR&(x%,8))     ! swap low/high byte
     ENDFUNC
Now you should be able to extract the low and high byte of a word :
     low.byte|=BYTE(x)
     high.byte|=BYTE(@intel.word(x))


MAX

This is how you could find the highest value in a word-array :
     PROCEDURE max.array(VAR proc(),high)
       ' *** return highest value of array proc()
       LOCAL last,n
       last=DIM?(proc())-1
       high=proc(1)                ! proc(0) ignored
       FOR n=2 TO last
         high=MAX(high,proc(n))
       NEXT n
     RETURN
I often store special information in the element with index 0.


Correlation

Use the Procedure Correlate to determine the correlation between two
arrays.
                               7.  STRINGS


INSTR

The command INSTR(a$,b$,i) always returns '1' if a$=b$. For i=1 that's
fine, but not for i>1. Don't blame me, I'm just the messenger.


LSET and RSET

If you use LSET or RSET, the string is padded with spaces :
     a$="  345"
     LSET a$="12"
     PRINT a$       ! the interpreter prints "12   ", not "12345"

You can use RSET for right justification of columns :
     f$=SPACE$(10)
     FOR i=1 TO 10
       RSET f$=text$(i)
       PRINT f$
     NEXT i


Parser

Parsing a string, you will frequently have to split the string into the
target$, the string before and the string after that target$. The
following functions could be helpful :
     FUNCTION before$(source$,target$)
       ' *** returns part of source$ before target$
       ' *** returns complete source$ if no target$ found
       LOCAL p
       p=INSTR(source$,target$)
       IF p=0
         RETURN source$
       ELSE
         RETURN LEFT$(source$,p-1)
       ENDIF
     ENDFUNC
     '
     FUNCTION after$(source$,target$)
       ' *** returns part of source$ after target$
       ' *** returns nullstring if no target$ found
       LOCAL p
       p=INSTR(source$,target$)
       IF p=0
         RETURN ""
       ELSE
         RETURN MID$(source$,p+LEN(target$))
       ENDIF
     ENDFUNC


                            8.  KEYBOARD INPUT


INKEY$

All keypresses are saved in the keyboard-buffer. If you don't want INKEY$
to read an "old" key, you should first clear the buffer :
     REPEAT
     UNTIL INKEY$=""     ! clear keyboard-buffer
     key$=""
     REPEAT
       key$=INKEY$       ! wait for new key
     UNTIL key$<>""

In the following table you'll find a few useful decimal ASCII-codes you
can use after 'key$=INKEY$'. In the third column the hexadecimal scan-code
of the key is also mentioned (see paragraph 'KEYGET').

     key                   ASC(key$)       scancode
     <Backspace>               8             &H0E
     <Tab>                     9             &H0F
     <Return> and <Enter>     13             &H1C and &H72
     <Esc>                    27             &H01
     <Delete>                127             &H53

     key               ASC(RIGHT$(key$))
     <F1>                     59             &H3B
     <F10>                    68             &H44
     <Shift> <F1>             84             &H54
     <Shift> <F10>            93             &H5D
     <Help>                   98             &H62
     <Undo>                   97             &H61
     <Insert>                 82             &H52
     <ClrHome>                71             &H47
     <Left arrow>             75             &H4B
     <Right arrow>            77             &H4D
     <Up arrow>               72             &H48
     <Down arrow>             80             &H50

Keys in the second part of this table return a 2-byte value after INKEY$.
You only need the low byte, the high byte is &H00. That's why a Standard
Global like help$ is defined as 'CHR$(0)+CHR$(98)'. Then it's easy to
check if <Help> was pressed :
     IF key$=help$
       (...)                  ! <Help>
     ENDIF
Otherwise, you have to test as follows :
     IF ASC(RIGHT$(key$))=98
       (...)                  ! <Help>
     ENDIF
However, read the paragraph 'KEYGET' for the ultimate keypress-processor.

If you are just waiting for any keypress, you could use either of the
following methods (clear the keyboard-buffer first) :
     ~INP(2)             ! my favourite
     '
     KEYGET code%        ! perhaps this is clearer in a listing
     '
     REPEAT              ! a loop is also possible
     UNTIL LEN(INKEY$)
The latter method is needed if you are waiting for any keypress or any
mouse-click :
     REPEAT
     UNTIL LEN(INKEY$) OR MOUSEK


INPUT

If you don't want the question mark to appear after INPUT, use :
     LOCATE col,lin
     INPUT "",txt$
The nullstring and the comma are essential. Most of the time you'll need
something like :
     LOCATE col,lin
     INPUT "Enter your name : ",name$
But if the instruction-line is not the same as the INPUT-line, use :
     PRINT AT(col1,lin1);"Enter your name :"
     LOCATE col2,lin2
     INPUT "",name$

After INPUT, the user can press <Insert> to switch between Insert-mode and
Overwrite-mode. I have not been able to discover how to input character-
codes 0-31 after INPUT. It's not important anyway, but I read somewhere
you could use <Alternate> for this purpose. The Alternate-method can be
used for character-codes 128-255 (not 127). In the following table you'll
find some important characters with the decimal ASCII-code :

  character ASCII-code   character ASCII-code   character ASCII-code

     á    -    160          é    -    130          í    -    161
     à    -    133          è    -    138          ì    -    141
     ä    -    132          ë    -    137          ï    -    139
     â    -    131          ê    -    136          î    -    140

     ó    -    162          ú    -    163          ÿ    -    152
     ò    -    149          ù    -    151          ß    -    158
     Ö    -    148          ü    -    129
     ô    -    147          û    -    150

     α    -    224          ≡    -    240          ½    -    171
     β    -    225          ±    -    241          ¼    -    172
     δ    -    235          ≥    -    242          ²    -    253
     µ    -    230          ≤    -    243
     π    -    227          ÷    -    246
     τ    -    231          ≈    -    247

     ¢    -    155          ©    -    189
     £    -    156          §    -    221
     ƒ    -    159
If you want to use one of these characters after INPUT, you should hold
<Alternate> down, enter the code, and release <Alternate>. I hope your
printer-driver could digest this table...

You can use <Backspace>, <Delete>, <Left arrow> and <Right arrow> on an
INPUT-line, but also :
     <Up arrow>     - cursor to start of input-line
     <Down arrow>   - cursor to end of line
     <Esc>          - erase line
The first two feel slightly unnatural, I would prefer it the other way: up
to end, down to start.

Both INPUT and LINE INPUT use a special cursor, so it doesn't make much
sense to use XBIOS 21 (Curscon) to do something interesting with the TOS-
cursor.


INPUT$

For the input of a secret password, you could use something like :
     PRINT "type password (5 characters) : ";
     code$=INPUT$(5)
The password does not appear on the screen.


LINE INPUT

LINE INPUT uses the underscore (_) as the cursor in a window. After you
press <Return>, the underscore is not completely erased. The rightmost
pixel remains visible. I think this is a GEM-bug.


KEYTEST

The KEYTEST-function does not respond to keys such as <Help>, <Undo>, etc.


KEYGET

KEYGET waits for a keypress, just like INP(2). But KEYGET is far more
flexible, because it returns the ASCII-code and the scan-code of any key
and also the state of the special keys <Shift>, <Control>, <Alternate> and
<CapsLock>. Consult your manual for tables of ASCII-codes and scan-codes
(in the paragraph 'INKEY$' you already encountered some important codes).
Study the following example to get an impression of the easy way you can
examine all keypresses with KEYGET :

     @initio_keyget        ! assign variables to the three codes
     '
     DO
       KEYGET get_code%
       @keyget             ! process keypress there (not included)
     LOOP
     '
     PROCEDURE initio_keyget
       ABSOLUTE ascii|,V:get_code%+3
       ABSOLUTE scan|,V:get_code%+1
       ABSOLUTE status|,V:get_code%
     RETURN

You will have to write your own Keyget-Procedure. You can check if any of
the special keys has been pressed, by using BTST(status|,bit) :
     bit 0 = Right <Shift>
     bit 1 = Left <Shift>
     bit 2 = <Control>
     bit 3 = <Alternate>
     bit 4 = <CapsLock>
You could discover if the user had pressed <Control> <Down arrow> with :
     IF scan|=&H50 AND BTST(status|,2)
       (...)
     ENDIF

If you are only interested in monitoring the five special keys, you could
use BIOS 11 (Kbshift) as well :
     status|=BIOS(11,-1)
Use the same table as above to test if bit 0-4 is set.

You are advised to clear the keyboard-buffer before leaving the Procedure
Keyget.

In most cases the scan-code of a key is the same, whether you pressed a
special key simultaneously or not. But watch out for the following
exceptions! For <Shift> <F1> to <Shift> <F10> the scan-codes &H54 to &H5D
are returned (not &H3B to &H44). On an MS-DOS computer these codes are
used for the keys F11 to F20. The combinations <Control> <Left Arrow>
(&H73) and <Control> <Right Arrow> (&H74) also have special codes. Blame
MS-DOS. The combinations <Alternate> <1> to <Alternate> <=> have the
special codes &H78 to &H83. That's ALT1 to ALT= for MS-DOS.


KEYLOOK

According to an unconfirmed report, KEYLOOK does not function properly
with the pre-Blitter TOS.


KEYPRESS

KEYPRESS uses the same 4-byte format as KEYGET: &Hccss00aa. In it you
will recognize the ASCII-code (&Haa), the scan-code (&Hss) and the code
for the special keys (&Hcc). If you want to simulate the pressing of a key
in an Alert box, you will have to send both the ASCII-code and the scan-
code. Use &H1C000D to simulate the pressing of <Return>. Or &H04620062 for
<Control> <Help>, although that certainly won't help in an Alert box. If
you don't need the scan-code (e.g. with INPUT), you can use just KEYPRESS
&Haa.


KEYDEF

The editor always uses KEYPAD &X101110, so you will have to set bit 4
yourself (e.g. KEYPAD &X10000) before you will be able to use KEYDEF in
your program.


Keyboard

As far as I know, there are four different keyboards available : USA
(QWERTY), English (QWERTY), German (QWERTZ) and French (AZERTY). The key
with scan-code &H2B (to the right of <Return>) has a different ASCII-code
in each version :
     version   ASCII-code     character
     USA        &H5C (92)         \
     English    &H23 (35)         #
     German     &H7E (126)        ~
     French     &H40 (64)         @
You could use XBIOS 16 (Keytbl) to determine the keyboard-version :
     PROCEDURE keyboard.version
       SELECT PEEK(LPEEK(XBIOS(16,L:-1,L:-1,L:-1))+&H2B)
       CASE &H5C
         usa.keybrd!=TRUE
       CASE &H23
         english.keybrd!=TRUE
       CASE &H7E
         german.keybrd!=TRUE
       CASE &H40
         french.keybrd!=TRUE
       ENDSELECT
     RETURN

You should take into account the differences between the keyboard-versions
if you are writing a program that should run smoothly in any country.

In the following table I have gathered all keys that have not the same
meaning on the four keyboard-versions :

     scancode      USA     English    German    French
       &H0C         -         -         ß         )
       &H0D         =         =         -         '
       &H10         Q         Q         Q         A
       &H11         W         W         W         Z
       &H15         Y         Y         Z         Y
       &H1A         [         [         Ü         [
       &H1B         ]         ]         +         ]
       &H1E         A         A         A         Q
       &H27         ;         ;         ö         M
       &H28         '         '         Ä         \
       &H29         `         `         #         `
       &H2B         \         #         ~         @
       &H2C         Z         Z         Y         W
       &H32         M         M         M         ,
       &H33         ,         ,         ,         ;
       &H34         .         .         .         :
       &H35         /         /         -         =
       &H60        none       \         <         <

If you are going to use any scan-code from this table, you should be very
careful. It's not nice to ask a German user to press <Y>, but test for
scan-code &H15 in your program...

If you insist on doing things the hard way, you can find the ASCII-value
that is assigned to a key with XBIOS 16. Actually there are three tables:
one for a normal keypress, one for a shifted key and one for a keypress
with CapsLock on :
     keytbl%=LPEEK(XBIOS(16,L:-1,L:-1,L:-1))
     shift%=keytbl%+&H80
     capslock%=shift%+&H80
Now you can find the ASCII-code for any scan-code (< &H80) :
     ascii=PEEK(keytbl%+scancode)       ! normal key
     ascii=PEEK(shift%+scancode)        ! shifted key
     ascii=PEEK(capslock%+scancode)     ! CapsLock on


Keyclick, Keyrepeat and CapsLock

Normally, you need the Keyclick as an audible feedback. Sometimes you have
to switch the Keyclick off, e.g. while an XBIOS 32 song is playing :
     PROCEDURE key.click(switch!)
       IF switch!
         SPOKE &H484,BSET(PEEK(&H484),0)     ! keyclick on
       ELSE
         SPOKE &H484,BCLR(PEEK(&H484),0)     ! keyclick off
       ENDIF
     RETURN

If your program reacts slowly after a keypress, you probably have to
switch the Keyrepeat temporarily off :
     PROCEDURE key.repeat(switch!)
       IF switch!
         SPOKE &H484,BSET(PEEK(&H484),1)     ! key-repeat on
       ELSE
         SPOKE &H484,BCLR(PEEK(&H484),1)     ! key-repeat off
       ENDIF
     RETURN

You can switch CapsLock on or off with :
     PROCEDURE caps(switch!)
       IF switch!
         ~BIOS(11,BSET(BIOS(11,-1),4))       ! CapsLock on
       ELSE
         ~BIOS(11,BCLR(BIOS(11,-1),4))       ! CapsLock off
       ENDIF
     RETURN



                            9.  SCREEN OUTPUT


PRINT

It is very important to know if PRINT will be used on the so-called TOS-
screen (no windows opened), or in a window. TOS emulates the VT52-terminal
of Digital Equipment, so if you PRINT on the TOS-screen, the VT52-codes
will be interpreted as commands. But in a window these codes are printed
as characters!

In both High and Medium resolution you can PRINT 25 lines of 80
characters, but in Low resolution it's 25 lines of 40 characters only.

Normally you can't PRINT a character at position (80,25) in High or Medium
resolution, or at (40,25) in Low resolution. Try the following :
     PRINT AT(80,25);"X";
and you will see that a linefeed is executed automatically, in spite of
the semicolon after "X". On the TOS-screen you can put a character at this
position by using the VT52-command 'wrap off' :
     PRINT AT(80,25);"*wX";        ! use the Escape-character instead of *
After 'Esc w' the linefeed is suppressed. The easiest way to enter the
Escape-character in the GFA-editor is to hold <Alternate> down and then to
enter <2> <7>. If you PRINT a string that doesn't fit on the current line,
the remaining characters are either printed on the next line ('Esc v', the
default in the interpreter, not in a compiled program), or discarded
('Esc w'). Actually, after 'Esc w' all characters up to the first CHR$(10)
or CHR$(13) are discarded.

It's impossible to PRINT characters with ASCII-code 0-31 on the TOS-
screen. However, you can print any character with :
     OUT 5,code
If necessary, use LOCATE first.

After opening a window (OPENW x) the command DEFTEXT will change size and
colour of PRINTed text as well! One advantage is that you can now PRINT in
different colours on the screen.

On the TOS-screen, all PRINTed text has the same colour. This colour is
determined by colour-index 1 and is also used for the Alert-box and the
Fileselector. The background on the screen is determined by colour-index
0. This colour is used after CLS.

It is possible to PRINT in different colours on the TOS-screen, by using
the VT52-code 'Esc b'. The background of PRINTed text can be changed with
VT52-code 'Esc c'. Use the following functions to experiment :
     DEFFN ink$(color)=CHR$(27)+"b"+CHR$(color)
     DEFFN paper$(color)=CHR$(27)+"c"+CHR$(color)
Use the colour-table from the paragraph 'SETCOLOR' or be prepared to
become very frustrated. I use the Standard Array color.index() as the
colour-table in my programs, so I change the colour of the PRINTed text or
the back-ground with the Standard Functions :
     DEFFN ink$(color)=CHR$(27)+"b"+CHR$(color.index(color))
     DEFFN paper$(color)=CHR$(27)+"c"+CHR$(color.index(color))
Remember, the VT52-codes have to be PRINTed to become effective, like
this :
     PRINT @ink$(red);@paper$(green);" this text is eye-catching "
Note the spaces at beginning and end of the string to emphasize the text-
colour against the background-colour. Of course you have to declare the
variables red and green first (usually colour-index 2 and 3; or if you
don't use the VDI colour-index, try the numbers 1 and 2). I define the
default colours as Standard Globals in my programs. Before I forget, it
won't work in High resolution. Sorry, couldn't resist that one.

In order to catch the eye of the user in High resolution you can PRINT
reverse on the TOS-screen :
     PRINT "this is *p IMPORTANT *q"    ! enter Esc instead of *
Enter the Escape-character in the usual way. Note again the extra space
both before and after the word that should stand out. Of course you could
also use CHR$(27) :
     PRINT "this is ";CHR$(27);"p IMPORTANT ";CHR$(27);"q"
More difficult to read on the screen, but easier to Llist. I use the
Standard Function Rev$ in all programs :
     DEFFN rev$(txt$)=CHR$(27)+"p"+txt$+CHR$(27)+"q"

If you use a comma with PRINT, the cursor will jump to the next tabulator-
stop. Tab-stops are at position 1, 17, 33, 49 and 65. Try the following to
see what I mean (in High or Medium resolution) :
     PRINT "1","17","33","49","65","1","17"
If you use the comma after the last tab-stop, a linefeed is executed and
the cursor jumps to the first tab-stop on the next line.

The easiest way to use double quotes is by using double double quotes
(read this twice to make sure you understand it) :
     PRINT "double quotes printed the ""easy"" way"
In a DATA-line a single double quote suffices :
     DATA "look Ma, "double quotes" again"
Or, simply :
     DATA look Ma, "double quotes" again

Try the Procedure Fastprint in High resolution if you find PRINT too slow.
This Procedure prints about four times faster! VT52-commands are ignored,
because characters are copied straight from the font-table to the screen.


LOCATE

The syntax of PRINT AT and LOCATE is now less confusing :
     PRINT AT(column,line)
     LOCATE column,line
In older versions of GFA-Basic it was LOCATE line,column. Check this if
you run an old program and text is PRINTed on the wrong place.


PRINT TAB

PRINT TAB behaves strangely if the position is greater than 80. Try the
following in High or Medium resolution :
     FOR i=0 TO 30
       PRINT TAB(i*20);i;
     NEXT i
One way to solve this problem is :
     PRINT TAB(MOD(i*20,80));i;         ! do use semicolons
But I think this is a GFA-bug that probably will be corrected in future
versions.

You can combine TAB with PRINT AT and with PRINT USING :
     PRINT AT(1,1);"1";TAB(40);"40"
     PRINT TAB(40);USING "##",40


Setscreen (XBIOS 5)

With XBIOS 5 (Setscreen) it is possible to change the resolution from Low
to Medium and from Medium to Low. Unfortunately, GEM ignores the switch,
so GEM-commands (e.g. ALERT, TEXT, MOUSE) do not work properly! But you
could change from Low to Medium resolution to show text on the TOS-screen
with PRINT (and VT52-commands). Most users will be grateful for the
improved readability of the text :
     ~XBIOS(5,L:-1,L:-1,1)    ! switch from Low to Medium
     (...)                    ! print text in Medium resolution
     ~XBIOS(5,L:-1,L:-1,0)    ! and go back to Low
If you change the resolution, the VT52-emulator is automatically
initialised. You'll probably have to adjust the palette before you can
read the text without sun-glasses. Don't forget to save and restore the
old palette.

XBIOS 5 is very useful if you would like to draw on a screen before
showing it to the user. Drawing on an "invisible" screen is indeed
possible, because the operating system uses two screens: the physical
screen (visible on your monitor) and the logical screen (usually, but not
necessarily, the same as the physical screen). All graphical (GEM-)com-
mands, including the TEXT-command, are always sent to the logical screen.
But TOS will send PRINT-commands to the physical screen, unless you've
opened a window! If the address of logical and physical screen is not the
same, you have your invisible screen (except for PRINTing on the TOS-
screen). The address of the logical screen must be a multiple of 256.
Study the Procedures Initio.logical.screen, Swap.screen and
Restore.physical.screen to see how you could use the described method for
animation :
     PROCEDURE initio.logical.screen
       ' *** global :   SCREEN.1%   SCREEN.2%
       DIM screen.2|(32256)
       screen.2%=VARPTR(screen.2|(0))
       screen.2%=screen.2%+256-(screen.2% MOD 256)
       screen.1%=physbase%
       ~XBIOS(5,L:screen.2%,L:-1,-1)  ! invisible screen.2 is now active
     RETURN
     '
     PROCEDURE swap.screen
       ' *** physical and logical screen are swapped
       SWAP screen.1%,screen.2%
       VSYNC                                   ! avoid flash
       ~XBIOS(5,L:screen.2%,L:screen.1%,-1)    ! swap the screens
     RETURN
     '
     PROCEDURE restore.physical.screen
       ~XBIOS(5,L:physbase%,L:physbase%,-1)
     RETURN

On some ST-computers XBIOS 5 does not function properly after installation
of a RAM-disk. In that case you could change the address of the logical
screen with :
     VSYNC
     SLPOKE &H45E,adr%


Font

TOS has three built-in system-fonts. The default PRINT-font for High
resolution is the 8x16 font (equals DEFTEXT ,,,13 for TEXT), while the 8x8
font (equals DEFTEXT ,,,6) is used in Medium and Low resolution. You can
switch between these two fonts with the following Procedures :
     PROCEDURE font.8x16
       LOCAL a$,adr%
       a$=MKI$(&HA000)+MKI$(&H2009)+MKI$(&H4E75)
       adr%=VARPTR(a$)
       adr%=C:adr%()         ! address of font-table
       {INTIN}={adr%+8}      ! pointer to 8x16 system-font
       VDISYS 5,2,0,102
     RETURN
     '
     PROCEDURE font.8x8
       LOCAL a$,adr%
       a$=MKI$(&HA000)+MKI$(&H2009)+MKI$(&H4E75)
       adr%=VARPTR(a$)
       adr%=C:adr%()         ! address of font-table
       {INTIN}={adr%+4}      ! pointer to 8x8 system-font
       VDISYS 5,2,0,102
     RETURN
Both Procedures seem to have problems with the accessory QUICKST, but I
never use it with GFA-Basic because there are other problems (INPUT) as
well. If I don't use it, how did I discover this? Good question. The third
font is used for icons, but for some reason can not become the current
system-font. The VDI-function seems to work only with fonts containing
characters of width 8 pixels. The function is not officially documented
by Atari (?).

You can replace the system-font by a font that has been created with
FONTKIT by Jeremy Hughes (4114 byte A1_xxxxx.FON file for High
resolution). Use the Procedure Change.font for this purpose and call the
Procedure Normal.font to restore the original system-font :
     PROCEDURE change.font
       ' *** global :   NEW.FONT!   NORMAL.FONT%
       LOCAL adr%,new.font%
       '
       ' *** load A1_xxxxx.FON file (4114 bytes) here
       INLINE new.font%,4114
       '
       adr%=L~A-22
       normal.font%={adr%}
       SLPOKE adr%,new.font%
       new.font!=TRUE
     RETURN
     '
     PROCEDURE normal.font
       IF new.font!
         SLPOKE L~A-22,normal.font%
         new.font!=FALSE
       ENDIF
     RETURN
I have not yet discovered how to use a FONTKIT-font with TEXT. Yes, I
could load a new font after installing GDOS, but that's not what I'm
looking for. Is there a quick and not-dirty way to convince GEM that a new
font has been installed?

A font-table for the 8x16 font occupies 4096 bytes (16 bytes/character,
256 characters). A FONTKIT-font usually has a name attached at the end,
that's why I reserve 4114 bytes. TOS ignores the name completely, it's
only used by the accessory FONSEL.ACC. You can load any 4096-byte font in
the Procedure Change.font, you don't even have to change 4114 into 4096.
Although you lose 18 bytes if you don't.


                               10.  PRINTER


Printer ready

If you send data to your printer (HARDCOPY, LPRINT, etc.), your ST will
wait 30 looooooong seconds if the printer happens to be not ready. Always
check if the printer is ready before sending data to the printer, e.g. by
calling the following Procedure :
     PROCEDURE printer.ready
       LOCAL k
       DO
         EXIT IF GEMDOS(17)
         ALERT 3," printer| | not ready !!",1," OK ",k
       LOOP
     RETURN


HARDCOPY

You can send a screendump to the printer by using the command HARDCOPY or
by pressing <Alternate> <Help>. In both cases you can abort the screendump
by pressing <Alternate> <Help>.

You can use CONTROL.ACC to change the printer-parameters. Don't forget to
save the desktop, in order to store these parameters in the file
DESKTOP.INF. Look for '#b' with your disk-editor if you're curious. The
parameters will only be read from DESKTOP.INF if CONTROL.ACC is installed
after a reset! I suggest the use of XBIOS 33 (Setprt) in a program instead
of using CONTROL.ACC. For a screendump from the High resolution screen to
an Epson-compatible printer, clear bit 1 and set bit 2 :
     PROCEDURE screendump
       ~XBIOS(33,&X100)    ! screendump to Epson(-compatible) printer
       HARDCOPY
     RETURN
If you set bit 2, TOS assumes you connected an Epson-printer (960
pixels/line). Clear bit 2 and TOS assumes you have an Atari-printer (1280
pixels/line).

If you use HARDCOPY, the width/height ratio of the printout does not
correspond with that of the screen. For a reasonably fast 1:1 screendump,
study the Procedure High.screendump.epson (Epson FX-80, or other 9-pin
Epson-compatible printer) or the Procedure High.screendump.star24 (24-pin
Star LC24-10) :
     PROCEDURE high.screendump.star24
       LOCAL m$,b$,k,scrn.start%,col,b%,x,d%,p|,b1|,b2|,b3|,n
       lf$=CHR$(10)
       ff$=CHR$(12)
       DEFFN bit.image$(m,d)=CHR$(27)+"*"+CHR$(m)+CHR$(MOD(d,256))+
                                                               CHR$(d/256)
       DEFFN line.space$(n)=CHR$(27)+"3"+CHR$(n)
       initialize$=CHR$(27)+"@"
       scrn.start%=XBIOS(2)
       '
       LPRINT initialize$;
       FOR col=0 TO 79
         b%=scrn.start%+col
         LPRINT SPC(8);
         LPRINT @line.space$(24);
         LPRINT @bit.image$(33,800);
         FOR x=399 TO 0 STEP -1
           d%=ADD(b%,MUL(x,80))
           p|=BYTE{d%}
           IF p|=0
             OUT 0,0,0,0,0,0,0
           ELSE
             CLR b1|,b2|,b3|
             IF BTST(p|,0)
               b1|=7
             ENDIF
             IF BTST(p|,1)
               ADD b1|,56
             ENDIF
             IF BTST(p|,2)
               ADD b1|,192
               b2|=1
             ENDIF
             IF BTST(p|,3)
               ADD b2|,14
             ENDIF
             IF BTST(p|,4)
               ADD b2|,112
             ENDIF
             IF BTST(p|,5)
               ADD b2|,128
               b3|=3
             ENDIF
             IF BTST(p|,6)
               ADD b3|,28
             ENDIF
             IF BTST(p|,7)
               ADD b3|,224
             ENDIF
             OUT 0,b3|,b2|,b1|,b3|,b2|,b1|
           ENDIF
         NEXT x
         LPRINT
         EXIT IF INKEY$=esc$
       NEXT col
       LPRINT ff$;
       LPRINT initialize$;
     RETURN

For a more flexible approach, study the Procedure Degas.screendump (Star
LC24-10, possible formats : 27x17, 18x11, 13.5x8.5 or 9x5.5 cm).

It should be possible to send only a (GET-)rectangle to your printer with
XBIOS 36 (Prtblk) or V_OUTPUT_WINDOW (VDI 5,Escape 21). Anybody out there
who knows how?

Never, I repeat, never swap disks during a screendump, as this could be
fatal for the new disk. TOS ignores the write-protect state during a
screendump, so it will miss the disk-swap completely. TOS will use the old
FAT for the new disk, and that usually is fatal (no pun intended).

If you have installed a GFA-Basic printer-driver (e.g. PTEPSON.PRG), a
screendump seems to be impossible. The bit-image mode of the printer can't
be used after the driver has been installed.


Printer-commands

Most matrix-printers recognize either IBM- or Epson-commands (or both). I
use the following Procedure to define the most important printer-commands
for my Star LC24-10. Adapt the definitions to your own printer, but stick
to the names for the global variables and functions. Other users could
then use your programs easily after replacing the Procedure Initio.printer
with their own :
     PROCEDURE initio.printer
       ' *** initializes global printer-variables for Star LC24-10
       ' *** DIP-switch settings :
       '     1-1 OFF         2-1 ON
       '     1-2 ON          2-2 ON
       '     1-3 OFF         2-3 ON
       '     1-4 ON          2-4 ON
       '     1-5 ON          2-5 OFF
       '     1-6 ON          2-6 OFF
       '     1-7 ON          2-7 ON
       '     1-8 ON          2-8 ON
       '
       LOCAL c$,f$
       c$=CHR$(27)
       f$=CHR$(28)
       '
       draft.char$=c$+"x0"
       lq.char$=c$+"x1"
       '
       courier.style$=c$+"k0"+lq.char$
       prestige.style$=c$+"k2"+lq.char$
       orator.style$=c$+"k3"+lq.char$
       script.style$=c$+"k4"+lq.char$
       '
       normal.char$=c$+"q0"
       outlined.char$=c$+"q1"
       shadow.char$=c$+"q2"
       outlined.shadow.char$=c$+"q3"
       '
       italic.on$=c$+"4"
       italic.off$=c$+"5"
       '
       emphasized.on$=c$+"E"
       emphasized.off$=c$+"F"
       '
       underline.on$=c$+"-1"
       underline.off$=c$+"-0"
       '
       bold.draft$=draft.char$+emphasized.on$+double.on$
       bold.lq$=lq$+double.on$
       bold.off$=emphasized.off$+double.off$
       '
       superscript.on$=c$+"S0"
       superscript.off$=c$+"T"
       subscript.on$=c$+"S1"
       subscript.off$=c$+"T"
       '
       epson.set$=c$+"t0"
       ibm.set$=c$+"t1"+c$+"6"
       DEFFN special.on$(n)=c$+"\"+CHR$(MOD(n,256))+CHR$(DIV(n,256))
       DEFFN ibm.special$(n)=c$+"^"+CHR$(n)
       DEFFN epson.special$(n)=ibm.set$[e-mail]$(n)+epson.set$
       '
       pica$=c$+"P"
       '
       elite$=c$+"M"
       '
       condensed.on$=CHR$(15)
       condensed.off$=CHR$(18)
       '
       large.on$=c$+"W1"
       large.off$=c$+"W0"
       large.line$=CHR$(14)
       '
       courier.proportional$=courier.style$+c$+"p1"
       prestige.proportional$=prestige.style$+c$+"p1"
       proportional.off$=c$+"p0"
       '
       DEFFN master.mode$(n)=c$+"!"+CHR$(n)
       underline=128
       italic=64
       expanded=32
       LET double.strike=16
       emphasized=8
       condensed=4
       proportional=2
       elite=1
       '
       normal.size$=c$+"h"+CHR$(0)
       LET double.size$=c$+"h"+CHR$(1)
       quad.size$=c$+"h"+CHR$(2)
       LET double.height$=c$+"w1"
       normal.height$=c$+"w0"
       normal.width$=f$+"E"+CHR$(0)
       LET double.width$=f$+"E"+CHR$(1)
       triple.width$=f$+"E"+CHR$(2)
       '
       lf$=CHR$(10)
       DEFFN lf$(n)=c$+"f1"+CHR$(n)
       rev.lf$=c$+CHR$(10)
       '
       ff$=CHR$(12)
       rev.ff$=c$+CHR$(12)
       '
       justify.left$=c$+"a0"
       justify.right$=c$+"a2"
       justify.full$=c$+"a3"
       center$=c$+"a1"
       '
       reset$=c$+"@"
       '
     RETURN
Of course you could delete all variables you don't need in your program.
And it really would be nice if everyone uses the proposed names. One of
the strong points of Public Domain GFA-programs is that it's easy to adapt
a program. Or rather, it should be easy. Using the above Procedure is one
step in the right direction.


                                11.  FILES


Floppy Write Test

You are advised to switch the Write Verify test off :
     SPOKE &H444,0       ! test off
     SPOKE &H444,1       ! test on (default)
According to experts like Dave Small and Bill Wilkinson the Verify test is
a complete waste of valuable time if you write to a disk.


Step Rate

You will find the current step-rate of your drive with :
     PRINT DPEEK(&H440)
The following values are possible :
     0 -  6 ms
     1 - 12 ms
     2 -  2 ms
     3 -  3 ms (default)
The operating system only looks at this value after a reset (?). For an
external 5.25"-drive you probably have to use 12 ms.


RAM-disk

Drive D is often reserved for a RAM-disk. GFA will recognize a RAM-disk
with DFREE(4) only if it was already present at the time the interpreter
was loaded.

After switching off your 1040 ST you should wait at least 15 seconds
before switching on again. Otherwise an old RAM-disk (or something else in
RAM, e.g. a virus...) may still be present when you switch your computer
on again.

If a RAM-disk is not installed properly after a reset, the reason could be
hidden in the drive bit-table at &H4C2. The old TOS does not clear this
table and a RAM-disk can only be installed as drive D if bit 3 is cleared.
By the way, use drive C (bit 2) only for a harddisk.


DIR$()

Use GEMDOS 25 (Dgetdrv) to find the current drive and combine this with
DIR$(drive) to find the current path :
     drive=GEMDOS(25)         ! drive 0 - 15
     drive$=CHR$(65+drive)    ! drive A - P
     p$=DIR$(drive+1)
     IF p$=""
       path$=drive$+":\"      ! main directory
     ELSE
       path$=drive$+":"+p$+"\"
     ENDIF
With DIR$(0) you'll find the path of the current drive, not necessarily
drive A. DIR$(1) returns the path of drive A. GEMDOS remembers the last
used path for all available drives. See also the Standard Procedure
Get.path.

If you run GFA-Basic from the main directory and load a GFA-program from a
folder, DIR$(0) will return the nullstring (""), not the folder. After
using CHDIR with the folder-name, the correct path will be returned. I use
CHDIR in the Shell-programs, so the Standard Global default.path$ will
contain the path of the GFA-program. This makes life easier if you want to
load data-files from the same folder, but don't know the precise path when
you write the program. It would be nice if you could determine the path of
the running GFA-program in the program itself.

You can make an array-table of available drives with the aid of BIOS 10
(Drvmap) :
     DIM drive!(15)
     SELECT DPEEK(&H4A6)
     CASE 1
       drive!(0)=TRUE
     CASE 2
       drive!(0)=TRUE
       drive!(1)=TRUE
     ENDSELECT
     table%=BIOS(10)
     FOR n=2 TO 15
       IF BTST(table%,n)
         drive!(n)=TRUE
       ENDIF
     NEXT n

You can check if a harddisk is connected with :
     IF PEEK(&H472)<>0
       harddisk!=TRUE
     ENDIF


DIR and FILES

After DIR, FILES, TRON or DUMP you can slow down the scrolling with
<CapsLock>. You can temporarily stop the scrolling by holding down the
right <Shift>-key. The output after DIR fits on any screen, but the FILES-
output is too wide for Low resolution. DIR will show only files in the
current directory. FILES will also show folders (marked with *). With DIR
(and FILESELECT) you will not be able to see "hidden" files or "system"
files, but FILES will show all files. You can also search for hidden
and/or system files with FSFIRST and FSNEXT by setting bit 1 and/or bit 2
of the attribute-byte.

Perhaps you have noticed that after the command FILES the first two lines
are peculiar if you happen to be in a folder. The first "name" in a folder
is always '.' (one dot) and the second always '..' (two dots). Time and
date are incorrect, because the authors of (the old) TOS forgot to convert
these to MS-DOS format. In case of nested folders, the operating system
finds the preceding folder through a pointer of the '..'-file. That's why
you can use 'CHDIR ..' to return to the preceding folder. Don't try this
in the main directory, or you'll get an error.


FSFIRST and FSNEXT

The DTA-buffer is usually found at BASEPAGE+128 (it's always there after
start-up), but you should not count on it. Use FGETDTA() to find the
current address, before FSFIRST :
     dta.adr%=FGETDTA()
     e%=FSFIRST(format$,attr)
FSFIRST returns -33 if no file has been found. FSNEXT returns -49 if no
more files are found.

In an accessory it's safer to create a new DTA-buffer :
     old.dta%=FGETDTA()            ! old buffer
     dta$=STRING$(44,0)
     dta.adr%=V:dta$
     ~FSETDTA(dta.adr%)            ! new buffer
     (...)                         ! FSFIRST/FSNEXT
     ~FSETDTA(old.dta%)            ! restore old buffer
The Desktop will appreciate all this extra work.

The 44 byte DTA-buffer (Data Transfer Address) contains the following data
after a succesful FSFIRST or FSNEXT :
     offset
      0-20     - reserved
        21     - attribute-byte
     22-23     - time
     24-25     - date
     26-29     - file-length
     30-43     - filename (including the extension, terminated by &H00)
The attributes and the filename can be read from the buffer with :
     attr=BYTE{dta.adr%+21}
     file$=CHAR{dta.adr%+30}

The DTA-buffer is not an exact copy of the relevant information in the
directory of the disk. With a disk-editor you would find a slot of 32
bytes for each file or folder :
     offset
      0- 7     - file- or folder-name (without extension)
      8-10     - extension
        11     - attribute-byte
     12-21     - reserved
     22-23     - time
     24-25     - date
     26-27     - FAT-pointer
     28-31     - file-length
The first byte of the filename has a special meaning in the following
cases :
     &H00      - free slot, never used before
     &HE5      - erased file, now free slot
     &H2E      - subdirectory
Both time and date are stored in MS-DOS format. Consult your GFA-manual
for more information. The FAT-pointer, also in an MS-DOS format (Intel-
format : first low byte, then high byte), points to the first cluster of
the file. If you are looking at a folder, the FAT-pointer points to the
cluster where you will find the directory of this folder (subdirectory).
If you are looking at a subdirectory (i.e. you are in a folder), the first
two slots are reserved for the files '.' and '..' (&H2E and &H2E2E). This
has already been mentioned in the paragraph 'DIR and FILES'. Finally, the
file-length is stored in, you guessed it, MS-DOS format. You might wonder
what MS-DOS has to do with Atari-disks. Read the paragraphs 'Disk Format'
and 'File Allocation Table' for the explanation.

If you use the attribute-byte &X10000 you will find both folders and
files! If the folders in a directory don't have an extension and all files
do have an extension, you could find all folders in the main directory as
follows :
     e%=FSFIRST("\*",&X10000)      ! and e%=FSNEXT() for next folders

If you can't use this simple method, you'll have to check after each
successful FSFIRST/FSNEXT if it's a folder or a file :
     IF BTST(BYTE{dta.adr%+21},4)
       (...)                       ! yes, it's a folder
     ENDIF

Use the attribute-byte 0 (i.e. no bits set) to find ordinary files only.

Use attribute-byte &X1000 to find the disk-name :
     dta.adr%=FGETDTA()
     e%=FSFIRST("\*.*",&X1000)     ! finds disk-name only, not files
     disk.name$=CHAR{dta.adr%+30}

You can read the attributes of a file or folder with GEMDOS 67 (Fattrib) :
     attr%=GEMDOS(67,L:V:filename$,0,0)
If the file (or folder) is not found, attr% is -33 (or -34), otherwise
attr% contains the attributes in the usual format. You can even change the
attributes of files with :
     r%=GEMDOS(67,L:V:filename$,1,attribute%)
It's not possible to change the attributes of folders or the disk-name
with GEMDOS 67. One way to do that is to change the directory-sector with
the aid of BIOS 4 (Rwabs). If you really feel the urge to experiment, you
should realize that one tiny mistake could ruin the disk.


EXIST

You can use EXIST to test if a folder exists, but only if the folder
contains at least one file :
     IF EXIST("\FOLDER\*.*")
       (...)                  ! folder found
     ELSE
       (...)                  ! folder not found or empty folder
     ENDIF


LOF

The length of a file is easily determined with LOF :
     OPEN "I",#1,file$
     length%=LOF(#1)
     CLOSE #1

To determine the number of records in a random file you could divide the
file-length by the total FIELD-length.


TOUCH

Use this method with TOUCH :
     OPEN "U",#1,file$
     TOUCH #1
     CLOSE #1


NAME

With the old TOS you can only change the name of files, not of folders.
Even from the desktop you can't change the name of a folder, so choose it
carefully.


KILL

KILLing a file does not erase it from the disk. The first byte of the
filename is changed to &HE5. Unfortunately you can't restore a killed file
by simply changing this byte with a disk-editor. The operating system will
be able to find the first cluster of the restored file, because the first
FAT-pointer is located in the directory. The next clusters can only be
found through the FAT (File Allocation Table), but after KILL all pointers
to this file are irreversibly erased. If you have not killed any file on
the disk before your fatal mistake, you are extremely lucky and will find
all clusters have been stored consecutively. But after some killing and
saving on the disk, the file could be dispersed over the entire disk. Some
programs are able to help you, but you will have to recognize clusters as
belonging to the killed file. That's easy with ASCII-files, but almost
impossible with other files. So, don't KILL unless you have to.


File Copy

You can copy a file source$ to dest$ (use complete pathnames!) with :
     PROCEDURE file.copy(source$,dest$)
       LOCAL block%
       OPEN "I",#90,source$
       OPEN "O",#91,dest$
       block%=LOF(#90)
       WHILE block%>32000
         PRINT #91,INPUT$(32000,#90);
         SUB block%,32000
       WEND
       PRINT #91,INPUT$(block%,#90);
       CLOSE #90
       CLOSE #91
     RETURN

Do not copy a file "to itself" on a harddisk. Thanks to yet another bug in
TOS, this action could completely wipe out the harddisk. Or perhaps this
should be called a feature of TOS, put there to punish the crazy user who
tries to copy a file to itself.


Disk Format

A disk contains 80 concentric tracks (numbered 0 - 79) or more. Sometimes
the expression "cylinder" is used instead of "track". Each track is
divided into 9, 10 or even 11 sectors. One sector can contain 512 data-
bytes. In order to be compatible with MS-DOS, TOS formats a disk with 80
tracks and 9 sectors/track. Actually it's easy to fit 10 sectors in one
track. With a little more effort you can create room for 11 sectors, but
some drives run slightly too fast and are not able to read the 11th
sector!

With a disk-editor you can examine the 512 data-bytes of a sector, but
you can't examine the sector-layout without accessing the Floppy Disk
Controller (FDC) directly. In that case you would find the following
layout for each sector :
     data-separator (GAP)     - 15 bytes
     ID-Address mark          - 1 byte
     sector-header            - 4 bytes (track, side, sector, size)
     CRC of sector header     - 2 bytes
     data separator           - 37 bytes
     Data-Address Mark        - 1 byte
     data bytes               - 512 bytes
     CRC of data bytes        - 2 bytes
     data separator           - 40 bytes
The data separator bytes are there to synchronize the FDC properly. The
FDC recognizes the sector-header by the preceding ID-Address mark. The
sector-header itself contains information about the current track, side
and sector and also about the size of the data-field (usually 512 bytes).
The FDC checks both the sector-header and the data-field for corrupted
bytes by comparing a computed "checksum" with the stored CRC-value. The
operating system cannot read/write one byte from/to a sector, only
complete sectors are read or written. GFA-Basic takes care of all the
dirty work.

First some bad news. A CRC-error is not always recognized by the ROM of
520 ST's and 1040 ST's (bug in XBIOS 8, Floprd). If your palms are now
getting sweatty, you could check your most precious disks with XBIOS 19
(Flopver). This function checks for 'lost data, RNF- or CRC-errors'.
Create a buffer of 1024 bytes and call XBIOS 19. A sector (512 bytes) is
loaded from the disk in drive A or B (0 or 1) into the second part of the
buffer and checked. If a bad sector is found, the sector-number is stored
as a word in the first part of the buffer. After checking all sectors in
one track you have to examine the word-list in the buffer. Hope you will
find only &H0000 there. I leave the writing of this program as an exercise
to the reader. Never thought I would use that phrase myself. Allright,
here's something to get started :
     buffer$=STRING$(1024,0)
     adr%=V:buffer$
     r%=XBIOS(19,L:adr%,L:0,drive,1,track,side,9)  ! if 9 sectors/track
You should now be able to find out if the track on this side (0 or 1) is
OK. Good luck.

You can use BIOS 7 (Getbpb) to examine the disk-format in the so-called
BIOS-Parameter-Block (BPB) of the disk :
     bpb.adr%=BIOS(7,drive)   ! address of BPB, or 0 (= error)
In 9 words you'll find the following information in the BPB :
     offset
        0      - bytes/sector (usually 512)
        2      - sectors/cluster (usually 2)
        4      - bytes/cluster
        6      - number of directory-sectors
        8      - length of FAT
       10      - first sector of second FAT
       12      - first data-sector
       14      - total clusters
       16      - flag (not used)

Use GEMDOS 54 (Dfree) to find out how many free clusters are available, or
simply use DFREE if you want to know how many free bytes are available on
a drive. Due to a bug, GEMDOS misses the last two clusters on a disk. You
can't write to these clusters (2048 bytes down the drain...), but you can
read these clusters if they do contain data. That would be a miracle, or
an MS-DOS disk.

You'll probably use XBIOS 10 (Flopfmt) to format a disk from GFA-Basic. If
you do, use &H0000 as the virgin-value for the first 18 sectors, and then
&HE5E5 for all data-sectors. You can use either 9 or 10 sectors/track, not
11. If you use 10 sectors/track, you should fill the first two tracks with
&H0000 and fill sectors 19 and 20 with &HE5E5 afterwards (read the
paragraph 'Sectors'). I don't recommend more than 80 tracks, certainly not
more than 82 tracks. If XBIOS 10 returns a value other than 0, you'll find
a list of bad sectors in the buffer you used (terminated with &H00). If
one of the first 18 sectors is bad, you can throw the disk away.

Using XBIOS 10, the interleave-factor should be 1. This means the sectors
on a track are numbered consecutively: 1,2,3,4,etc. I don't understand
why some programmers use another value and call it 'Fast Format'. The FDC
needs more time to read a complete track if the interleave-factor is not
1. Perhaps they try to create the so-called Twisted (or Skewed) format.
TOS loses time if the head moves to the next track. Because the Seek with
Verify flag is set, the FDC first verifies the track-number and then reads
the sector-number. While checking the track-number, sector 1 was passing,
so we have to wait for one complete spin of the disk (200 ms, yawn) until
sector 1 can be read. One solution is to clear the Seek with Verify flag,
but that could lead to nasty problems if the head still rattles slightly
at the time sector 1 is read. The best solution is the Twisted format
(adopted by Atari from the Mega ST onwards). For a single-sided disk with
9 sectors on one track this means :
     track 0 : sector 1,2,3,4,5,6,7,8,9
     track 1 : sector 8,9,1,2,3,4,5,6,7
     track 2 : sector 6,7,8,9,1,2,3,4,5
     etc.
Now, sector 1 is encountered almost immediately after the track-number is
verified. A 1-sector offset is not possible, but a 2-sector offset is
enough to settle the rattling head. It is impossible to read data faster
from a disk! But I'm afraid you can't format a Twisted disk with XBIOS 10
if you have an old TOS. You have to use a special format-program.

If you format a disk from the desktop, bad clusters are flagged with a
special value in the FAT. However, if TOS 1.4 encounters a bad sector,
something goes wrong and the FAT is corrupted. One more reason to quit
smoking, because smoke-particles definitely constitute a serious hazard to
the health of your disks.

You can use XBIOS 18 (Protobt) to create a bootsector on the formatted
disk. Don't worry about the media-byte (disk-type), because TOS doesn't
use it. Do use &H1000000 to generate a random serial number, because it is
very important that different disks have different serial numbers! Write
the bootsector to the disk with XBIOS 9 (Flopwr), not with BIOS 4 (Rwabs):
     r%=XBIOS(9,L:buffer%,L:0,drive%,1,0,0,1)

Why are different serial numbers so important? If TOS suspects a disk-
swap, the serial number is read from the disk. A disk-swap can only be
recognized if the number on the new disk is different from the old number.
If the new disk contains the same serial number, TOS uses the FAT of the
previous disk. Writing to a swapped disk will probably zap it, if you
follow me. Disk-copiers copy everything, including serial numbers. Be
careful!

Although it is possible to format a disk from GFA-Basic, I don't recommend
it (now he tells us...). My favourite format is :
     80 tracks
     10 sectors/track
     Twisted format
I use TWISTER.PRG (not Public Domain, as far as I know), but you could use
a Public Domain program like DCOPY (actually Shareware). The Desktop can't
copy a Twisted disk, but file-copy is always possible. DCOPY copies any
format, including Twisted format.
File Allocation Table (FAT)

The first sector on a disk is the boot-sector. The next five sectors are
reserved for the FAT. And the next five for a copy of the FAT (actually
it's the other way around). Finally, the main (or root) directory occupies
the next 7 sectors (32 bytes for each slot). This means that the first 18
sectors (No. 0-17) are reserved for the operating system. All other
sectors are available for storing files.

The storage-unit for files is a cluster. A cluster consists of two
consecutive sectors (1024 bytes). A file that contains only 1 byte will
therefore still occupy 1024 bytes (1 K) on the disk. When a file is saved,
the operating system looks for the first empty cluster, then the next,
etc. Information about available clusters is stored in the FAT as a
collection of pointers. Due to inefficient programming, the search for
free clusters takes a long time. Try DFREE on a harddisk and you'll agree.
Install a program like FATSPEED.PRG (Public Domain, by Ulrich Kuebler) to
speed this up!

The first three bytes of the FAT are not used by TOS, but are there to
enable MS-DOS to read an ST-formatted disk. TOS writes &HF7FFFF, where the
first byte (&HF7) is supposed to be the media-byte. Unfortunately MS-DOS
doesn't understand this and refuses to read the directory properly. I'm
not quite sure why, but changing the first three bytes to &H000000 seems
to work. You could try &HF8FFFF (80 tracks, 9 sectors/track, single sided
disk) or &HF9FFFF (double sided disk) instead. Or you could use the media-
byte at offset 21 from the bootsector. To make your MS-DOS friends
completely happy, you should change the first three bytes of the bootsec-
tor to: &HEB3890. Sometimes (DOS 4.0 ?) you have to change the next three
bytes as well: &H49424D (that's IBM in ASCII; please watch your language).
Better still, let them use their own disk editor on their MS-DOS computer
(e.g. Norton Utilities). Why should you do all the work? By the way, your
ST should be able to use an MS-DOS disk without any modifications.

Each FAT-pointer consists of one and a halve byte (3 nibbles, i.e. 12
bits). In hexadecimal notation this means three digits for one pointer.
The first pointer (No. 0) points to cluster No. 0, the second to No. 1,
etc. . Because the first two pointers don't count, you have to subtract
two to find the actual cluster (pointer 2 points to cluster No. 0, etc.).
The first cluster starts at sector No. 18 (remember, sectors 0-17 are
reserved for bookkeeping), so you could find the first sector of a cluster
with :
     (pointer - 2) * 2 + 18
The second sector of this cluster is of course the next one.

TOS reads the pointers in a peculiar (MS-DOS) way. Suppose the FAT-sector
starts with :
     F7 FF FF 03 40 00 FF 0F 00
Without further explanation, this translates to :
     FAT-pointer 0 and 1 are ignored
     FAT-pointer 2 = &H003 (next cluster on sector 20 + 21)
     FAT-pointer 3 = &H004 (next cluster on sector 22 + 23)
     FAT-pointer 4 = &HFFF (last cluster of this file)
     FAT-pointer 5 = &H000 (free cluster)
In order to understand this, you have to consult the following table :
     &H000         : cluster still available
     &HFF1 - &HFF7 : bad cluster, never available
     &HFF8 - &HFFF : last cluster of this file (End Of File)
     &H002 - &HFF0 : pointer to next cluster
Assuming the FAT-pointer &H002 at offset 26 in the directory (you'll find
&H0200 with a disk editor, that's Intel format with low byte first again),
you should be able to figure out that this file will be found in sectors
18 through 23. Sectors 24/25 are empty, so this cluster is available for a
new file. Any questions? The one big advantage of all this is compatibi-
lity with MS-DOS disks. With TOS 1.4 your ST-disks can be made completely
compatible, so you don't even have to change a few bytes.

Right, you have just read the Fatman-book. The movie will be released
shortly, but you can NOW buy those fabulous Fatman-shirts and fantastic
Fatman-buttons. Call Atari for further details.


Sectors

There are two different methods to assign a number to a sector. The first
one is to number the "physical" sectors in each track from 1 to 9
(assuming 9 sectors/track). This way you could say the bootsector is
sector 1 on track 0 (on side 0 if the disk is double sided). But GEMDOS
doesn't care about tracks or sides, it counts "logical" sectors from 0 to
719 (80 tracks, 9 sectors/track, one sided disk) or from 0 to 1439 (double
sided disk). According to GEMDOS, the bootsector is on sector 0. And on a
double sided disk, physical sector 1 on track 0 of side 1 (the other side)
would be sector 9.

With BIOS 4 (Rwabs) you can read (and write) complete logical sectors :
     buffer$=SPACE$(512)      ! 512 bytes for 1 sector
     buffer%=V:buffer$        ! address of buffer
     r%=BIOS(4,0,L:buffer%,1,sector%,drive%)      ! load the sucker
You would load the bootsector from the disk in drive A with :
     r%=BIOS(4,0,L:buffer%,1,0,0)
You can use BIOS 4 not only with floppy disks, but also with a harddisk
or a RAM-disk. After loading a sector, you can read one byte with :
     b|=BYTE{buffer%+n}       ! n from 0 to 511
You can read a word with :
     w=WORD{buffer%+n}
But only if the word starts at an even address. Otherwise you have to use:
     w=BYTE{buffer%+n+1}+256*BYTE{buffer%+n}
If necessary, you can speed this up by using the special integer commands
for addition and multiplication. How about this Polish monster :
     DEFFN word(adr%)=ADD(BYTE{SUCC(adr%)},MUL(256,BYTE{adr%}))
Then you would use :
     w=@word(ADD(buffer%,n))

If you use BIOS 4 to write a sector after formatting a disk, you should
use '3' as a flag (not '1') :
     r%=BIOS(4,3,L:buffer%,1,sector%,drive%)

You can also read and write physical sectors with XBIOS 8 (Floprd) and
XBIOS 9 (Flopwr). With these commands you could even read/write all
sectors on one track. This is the only way to read a track, because
reading a complete track is impossible due to a bug in the FDC.

If you swap a disk after loading/writing a sector you should be careful.
Testing with BIOS 9 (Mediach) you could miss the disk-swap. This could be
fatal, because TOS uses the FAT of the other disk! I think you could use
BIOS 7 (Getbpb) in most cases, but use the Procedure Force.mediach if in
doubt :
     PROCEDURE force.mediach
       LOCAL x$,old.vector%,a%
       x$=SPACE$(12)
       old.vector%=LPEEK(&H47E)
       a%=V:x$
       DPOKE a%,&H2B7C
       LPOKE a%+2,old.vector%
       DPOKE a%+6,&H47E
       DPOKE a%+8,&H7002
       DPOKE a%+10,&H4E75
       SLPOKE &H47E,a%
       ~DFREE(0)              ! current drive
     RETURN
To be more precise, BIOS 7 can't be used in the following situation :
     - TOS reads a sector
     - you swap disks
     - you use BIOS 7 in your program
     - TOS reads a sector
Now TOS will assume there has been no disk-swap, because there has been no
disk-swap after the last BIOS 7 call! You definitely need the Procedure
Force.mediach in this case.

By the track, TOS also ignores disk-swaps during a screendump (HARDCOPY),
or while using DMA (harddisk, laser printer). TOS detects a disk-swap by
monitoring the write-protect state. To see this, you should turn all
lights off and then watch the drive-light closely. Closer. You can turn
the lights on again. If the drive is empty, TOS gets a write-protect
signal and assumes the user might have swapped disks. BIOS 9 should return
'1' at this point. TOS checks if you really did swap disks by reading the
serial number from the bootsector and comparing it with the current
number. Only if these numbers are different, a disk-swap is recognized by
TOS (BIOS 9 should return '2' now). You probably deduced that TOS will
read the bootsector also if you use a write-protected disk. Continuously
reading the bootsector is a waste of time, so TOS waits 1.5 seconds before
looking again. Never swap disks within 1.5 seconds after a read/write-
operation. The drive keeps spinning for 2 seconds, so you can't go wrong
if you wait until the drive-light is off before swapping disks.

Bootsector

In the following table you'll find the lay-out of a bootsector. All words
are in Intel-format, except CHKSUM.

     offset    length    name

        0        2                 &H6038 = branch to bootroutine
        2        6       FILLER    fill-bytes
        8        3       SERIAL    serial-number of disk

       11        2       BPS       bytes/sector (512)
       13        1       SPC       sectors/cluster (2)
       14        2       RES       reserved sectors (1, Bootsector)
       16        1       NFATS     number of FAT's (2)
       17        2       NDIRS     max. entries in main directory
       19        2       NSECTS    total sectors
       21        1       MEDIA     media-byte (not used by TOS)
       22        2       SPF       sectors/FAT (5)
       24        2       SPT       sectors/track
       26        2       NSIDES    sides (1 or 2; no joke this time)
       28        2       NHID      hidden sectors (ignored by TOS)

       30        2       EXECFLAG  start of bootcode : flag
       32        2       LDMODE    0=load FNAME; <>0=load sectors
       34        2       SSECT     first sector (LDMODE<>0)
       36        2       SECTCNT   number of sectors
       38        4       LDADDR    load at this RAM-address
       42        4       FATBUF    address of FAT-buffer
       46       11       FNAME     filename (nnnnnnnneee) (LDMODE=0)
       57        1       DUMMY     fill-byte

       58                          boot-routine (could be a boot-virus)

      510        2       CHKSUM

TOS determines if the bootsector is executable by adding all bytes. If
this sum (AND &HFFFF) equals &H1234, the bootsector is executable. If you
use GFA-Basic this probably means you have an ancient ST with TOS in RAM,
or a boot-virus. A normal GFA-disk has only &H00- or &HE5-bytes from the
offset 58.


BLOAD

BLOAD needs an address, unless you have used BSAVE in the same program
before. In that case the BSAVE-address is used automatically by BLOAD if
you don't specify a new address.

BLOAD (BSAVE) is easier to use than BGET (BPUT), because you don't have to
open the file. But with BLOAD you can only load the entire file, while
BGET allows you to load any part of the file.


INP and OUT

Both INP and OUT can also be used with 2-byte and 4-byte integers :
     a|=INP(#n)
     a&=INP&(#n)
     a%=INP%(#n)
     OUT #n,a|
     OUT& #n,a&
     OUT% #n,a%


INPUT and LINE INPUT

Because GFA now uses a 4K-buffer for each opened file (version 3.07),
reading data from a file with (LINE) INPUT goes much faster.


STORE and RECALL

For very fast loading and saving of string-arrays, you should use RECALL
and STORE. You can also store (or recall) a part of an array as follows :
     STORE #1,txt$(),10       ! store elements 0 through 9
     STORE #1,txt$(),5 TO 10  ! store elements 5 through 10

The correct syntax is :
     STORE #i,x$()[,n[ TO m]]
     RECALL #i,x$(),n[ TO m],x%    (use n=-1 for complete array)
Of course you have to open the file first.

If you STORE a text-array, GFA puts &H0D0A (CHR$(13);CHR$(10)) after each
element. This is the same format as used by 1st Word Plus (WP Mode off,
i.e. ASCII-mode), Tempus, etc.

If you're going to show more than a few text-lines, you could enter the
text as DATA-lines, e.g. with the Procedures Initio.text.array and
Initio.text.array.low (for Low resolution) :
     PROCEDURE initio.text.array
       ' *** global :  TEXT$()
       LOCAL lines,line$,n
       lines=0
       RESTORE txt.data
       READ line$
       REPEAT
         INC lines
       READ line$
       UNTIL line$="***"
       ERASE text$()
       DIM text$(lines)
       RESTORE txt.data
       FOR n=1 TO lines
         READ text$
         text$(n)=SPACE$(5)+text$           ! left margin of 5 spaces !!
       NEXT n
       txt.data:
       DATA text
       DATA ***
     RETURN

If you are going to show more text, I suggest you use 1st Word Plus, or
any other wordprocessor or text-editor that can save your text as an
ASCII-file. With 1st Word Plus, I use a Ruler length of 70 and the
following Page Layout Form :
     Paper length   66
     TOF margin     19
     Head margin     4
     Foot margin     4
     BOF margin     19
     Lines/page     20
Enter the text and save as an ASCII-file (turn WP Mode off before saving).
In your GFA-Basic program you would first load the text in a string-array:
     DIM text$(lines)
     OPEN "I",#1,file$
     RECALL #1,text$(),-1,lines%   ! lines% ≤ lines+1
     CLOSE #1
Then you could use the Procedure Show.text.page (High or Medium resolu-
tion) to show the text with 20 lines/screen. The Procedure uses a left and
right margin of 5 characters, so that's why you have to use 70 charac-
ters/line in your wordprocessor. If the text-array is full, you won't get
an error if the file contains more text-lines!

You could use a 2-dimensional string-array to store first and last names :
     name$(i,0)=first_name$
     name$(i,1)=last_name$
Again, STORE and RECALL are very fast. But it is now necessary to use
exactly the same dimensions with RECALL that you used with STORE. If the
dimensions don't match, the array will be scrambled after RECALL.


FILESELECT

Don't use the underscore '_' in the path-line of the Fileselector, because
a bug in the old TOS will then cause a few bombs. Owners of a Mega ST or
TOS-version 1.4 can use as many underscores as they like.

Changing drives in the Fileselector (old TOS) is not easy. Click on the
path-line and press <Esc> to clear the line. Enter the drive, e.g. 'D:\',
and click on the bar under the path-line in order to read the new
directory. Also click on this bar after changing disks (in this case you
would press <Esc> on the desktop). Selecting drive A is easier: just clear
the path-line and click on the bar. The TOS-code that takes care of all
this work is also known as the bartender.

If you have changed the extension in the path-line, you should click just
below the bar. If you click on the bar, the path-line is overwritten with
'*.*' ! That same bartender strikes again.

The correct syntax for calling the Fileselector is :
     FILESELECT [#title$,]path$,default$,file$
The title is only used in TOS-version 1.4 and ignored in older TOS-
versions. The default$ usually is the null-string (""), but don't use the
null-string for path$ or the Fileselector will freeze. Use "\*.*" as path$
for all files in the main directory. Do use the backslash in the pathname
(e.g. "A:\*.*"). Due to a bug in GEM, the wrong drive is sometimes used if
you forget the backslash ("A:*.*"). If the user has selected a file, file$
will contain the path and filename. The file$ will be the null-string if
the user selected <Cancel>. A third possibility is easily overlooked: the
user could have selected <OK> without choosing a file. In that case file$
contains the current path, ending with a backslash.

Do not despair if you need a title, but don't have TOS 1.4. Try the
Procedure Fileselect (High or Medium resolution) or Fileselect.low :
     PROCEDURE fileselect(path$,default$,txt$,left$,right$,VAR file$)
       ' *** print optional title (light text) to left and right
       LOCAL screen$,y.fac
       SGET screen$
       CLS
       IF high.res!
         y.fac=1
       ELSE
         y.fac=2
       ENDIF
       DEFTEXT black,2,900,32
       TEXT 100,350/y.fac,300/y.fac,left$
       DEFTEXT ,,2700
       TEXT 540,50/y.fac,300/y.fac,right$
       DEFTEXT ,0,0,13
       PRINT AT(1,3);@center$(txt$)
       GRAPHMODE 3
       DEFFILL black,1
       BOUNDARY 0
       IF high.res!
         BOX 157,25,482,54
         PLOT 157,25
         PBOX 159,27,480,52
       ELSE
         BOX 157,12,482,27
         PLOT 157,12
         PBOX 160,14,479,24
       ENDIF
       BOUNDARY 1
       GRAPHMODE 1
       FILESELECT path$,default$,file$
       SPUT screen$
     RETURN
As a programmer, you should take into account the possibility that a user
might start your program from drive A, a harddisk or a RAM-disk. I use the
Standard Global default.path$ to remember where the program was started.
If the user changes the (default) path in the Fileselector, you should
note the change and use the new path if the Fileselector is called again.
Use the Procedure Parse.filename for this purpose :
     PROCEDURE parse.filename(parse.name$,VAR drive$,path$,file$,ext$)
       LOCAL pos,first,last,last!,search,parse.file$
       '
       parse.name$=UPPER$(parse.name$)
       IF MID$(parse.name$,2,1)=":"
         drive$=LEFT$(parse.name$,1)
       ELSE
         drive$=CHR$(65+GEMDOS(&H19))    ! current drive
       ENDIF
       '
       pos=1
       last!=FALSE
       last=0
       first=INSTR(1,parse.name$,"\")
       REPEAT
         search=INSTR(pos,parse.name$,"\")
         IF search>0
           pos=search+1
           last=search
         ELSE
           last!=TRUE
         ENDIF
       UNTIL last!
       IF last>0                              ! backslash discovered
         path$=MID$(parse.name$,first,last-first+1)
         parse.file$=MID$(parse.name$,last+1)
       ELSE                                   ! no '\'
         path$=""
         pos=INSTR(1,parse.name$,":")
         IF pos>0
           parse.file$=MID$(parse.name$,pos+1)
         ELSE
           parse.file$=parse.name$
         ENDIF
       ENDIF
       pos=INSTR(parse.file$,".")
       IF pos>0                               ! name with extension
         ext$=MID$(parse.file$,pos+1)
         file$=LEFT$(parse.file$,pos-1)
       ELSE                                   ! name without extension
         ext$=""
         file$=parse.file$
       ENDIF
     RETURN

If you have a joystick with Auto-Fire on, you should switch it off. The
Fileselector doesn't like Auto-Fire. Neither do I.

The Fileselector will warn you with a modest 'ping' if it counts more than
100 files/folders. It will show only the first 100 files/folders. I think
45 files in one folder is really the limit for impatient users like
myself. More than 100 is a crime that should be punished with more than a
'ping'. The main directory of drive A can't contain more than 112
files/folders, because the 7 directory-sectors contain 112 32-byte slots.

Every time you open a folder (in the Fileselector, or otherwise), TOS
stores information about the folder in a table. After opening/accessing 40
folders, TOS will delete clusters, cross-link clusters, and do other nasty
things. Your disk could be completely destroyed, thanks to this bug. Atari
enlarged the buffer in TOS 1.2 and fixed the bug in TOS 1.4. Atari also
distributes the program FOLDRxxx.PRG to extend the 40-folder limit with
100 (FOLDR100.PRG) or more. Be careful with SHOW INFO, it's easy to exceed
the 40-folder limit! You could recognize a disaster by one of the
following symptoms :
     - unexpected '0 bytes in 0 items' message in directory
     - folder-names trashed (usually lots of Greek letters)
     - Show Info crashes or shows weird information
Don't be afraid of a new virus. It's only a TOS-bug. Immediately reset
your ST, try to salvage as many files as possible and reformat the disk.
If all files are lost, you will have to use your back-up files. If you
don't have back-up files, you have nothing left but my sympathy.


                                12.  MIDI


INPMID$

With the command INPMID$ the internal Midi-buffer is read and at the same
time cleared. You can find the buffer with XBIOS 14 (Iorec) :
     adr%=LPEEK(XBIOS(14,2))
The default size of this buffer is only 128 bytes, but you can use the
Procedure Change.midi.buffer to change the size of the buffer :
     PROCEDURE change.midi.buffer(size%)
       LOCAL ptr%
       ptr%=XBIOS(14,2)
       ERASE buffer|()
       DIM buffer|(size%-1)
       LPOKE ptr%,VARPTR(buffer|(0))   ! start-address of new buffer
       DPOKE ptr%+4,size%              ! size
       DPOKE ptr%+6,0                  ! buffer-head
       DPOKE ptr%+8,0                  ! buffer-tail
       DPOKE ptr%+10,0                 ! low mark (not used)
       DPOKE ptr%+12,size%-1           ! high mark (not used)
     RETURN
Because handshake is impossible with Midi, you need a large buffer if
Midi-bytes are coming in fast.


INP

If you use INP(3) to read Midi-bytes, you should first check with INP?(3)
if the Midi-buffer contains data. If you use INP(3) and no bytes are
available, your ST will freeze. Until you reset the computer.


Midi-commands

Study the Procedures in the file MIDI.LST to see how you can use Midi-
commands in GFA-Basic. With the Procedures Record.midi and Play.midi you
could write a simple Midi-recorder. And the Procedure Midi.monitor can be
used to examine incoming Midi-messages.
     PROCEDURE record.midi(VAR midi.byte|(),midi.time%())
       ' *** uses Procedure All.midi.off
       ' *** global :  LAST.MIDI.BYTE%
       LOCAL last%,buffer$,i%,t%,time%,byte|,delay%,j%,m$,k
       ARRAYFILL midi.byte|(),0
       ARRAYFILL midi.time%(),0
       last%=DIM?(midi.byte|())-1
       m$=STR$(last%)+" bytes available ;| |stop recording|"
       m$=m$+"by pressing space"
       ALERT 3,m$,1,"RECORD",k
       REPEAT
       UNTIL INKEY$=""
       buffer$=INPMID$         ! clear MIDI-buffer
       i%=1
       t%=TIMER
       REPEAT
         IF INP?(3)
           byte|=INP(3)
           IF byte|<>254
             time%=SUB(TIMER,t%)
             midi.byte|(i%)=byte|
             midi.time%(i%)=time%
             INC i%
           ENDIF
         ENDIF
       UNTIL i%=last% OR INKEY$=" "
       last.midi.byte%=i%-1
       @all.midi.off
       delay%=midi.time%(1)               ! subtract time for first note
       FOR j%=1 TO i%
         SUB midi.time%(j%),delay%
       NEXT j%
       m$="|"+STR$(i%)+" bytes recorded"
       ALERT 3,m$,1," OK ",k
     RETURN
     '
     PROCEDURE play.midi(VAR midi.byte|(),midi.time%())
       ' *** uses Procedure All.midi.off
       LOCAL m$,k,i%,t%,time%
       m$="record of "+STR$(INT(midi.time%(last.midi.byte%)/200))+
       m$=m$+" seconds| |(stop by pressing space)"
       ALERT 3,m$,1,"PLAY",k
       REPEAT
       UNTIL INKEY$=""
       i%=1
       t%=TIMER
       REPEAT
         time%=SUB(TIMER,t%)
         IF midi.time%(i%)<=time%
           OUT 3,midi.byte|(i%)
           INC i%
         ENDIF
       UNTIL i%=last.midi.byte% OR INKEY$=" "
       @all.midi.off
     RETURN
     '
     PROCEDURE midi.monitor
       LOCAL m$,k,byte|,byte$,hex$,bin$,buffer$,key$
       byte$=SPACE$(3)
       hex$=SPACE$(2)
       bin$=SPACE$(8)
       m$="all incoming bytes|(except 254) are|printed on screen ;|"
       m$=m$+"stop by pressing space"
       ALERT 1,m$,1,"START",k
       m$="press|<Return>|for CLS"
       ALERT 1,m$,1," OK ",k
       REPEAT
       UNTIL INKEY$=""
       buffer$=INPMID$      ! clear MIDI-buffer
       CLS
       PRINT TAB(10);"dec";TAB(20);"hex";TAB(30);"binary"
       REPEAT
          REPEAT
           key$=INKEY$
           IF INP?(3)
             byte|=INP(3)
             IF byte|<>254
               IF TIMER-t%>200
                 PRINT
               ENDIF
               t%=TIMER
               RSET byte$=STR$(byte|)
               RSET hex$=HEX$(byte|)
               RSET bin$=BIN$(byte|)
               PRINT TAB(10);byte$;TAB(20);hex$;TAB(30);bin$
             ENDIF
           ENDIF
         UNTIL key$=" " OR key$=CHR$(13)
         IF key$=CHR$(13)
           CLS
         ENDIF
       UNTIL key$=" "
       @all.midi.off
       REPEAT
       UNTIL INKEY$=""
       PRINT " (press any key)"
       ~INP(2)
     RETURN


                                13.  MODEM


INPAUX$

With the command INPAUX$ the internal RS232-buffer is read and at the same
time cleared. You can find the address of the input-buffer with :
     adr.in%=LPEEK(XBIOS(14,0))
The output-buffer can be located with :
     adr.out%=LPEEK(XBIOS(14,0)+14)


INP

If you use INP(1) to read incoming bytes, you should always check with
INP?(1) if the RS232-buffer contains data.


Rsconf (XBIOS 15)

With XBIOS 15 (Rsconf) you can change the RS232-parameters. A few
baudrates :
     0 - 19200 baud
     1 -  9600 baud
     4 -  2400 baud
     7 -  1200 baud
     9 -   300 baud
    14 -    75 baud
Use -1 for parameters you don't want to change. Due to a TOS-bug, you
can't use 75 baud, because '14' results in 120 baud. Also, the old TOS
(pre-Blitter age) can't handle hardware handshake with RTS/CTS-signals.
Atari has released a bug-fix that should enable any TOS to use RTS/CTS.
Software handshaking (XON/XOFF) functions properly. The default
after power-up is no handshake protocol.


                                14.  MOUSE


Editor

Sometimes the editor seems to freeze while the cursor is blinking rapidly.
Just move the mouse and the editor comes alive again.


Fileselector

Sometimes the same blinking mouse appears after calling the Fileselector
or an Alert-box. I've read somewhere this could be due to the combination
of a VDI-function (for the mouse) and an AES-function (for Fileselector or
Alert-box). GFA takes care of the first and GEM of the second, and
sometimes this seems to result in a conflict.


MOUSE

If you repeatedly call a Procedure in which you test for a mouse-click,
you should incorporate a short pause in the Procedure (e.g. PAUSE 5).
Otherwise the Procedure might be called again while the user is still
holding the button down. You could also wait until the user releases the
button :
     REPEAT
     UNTIL MOUSEK=0      ! wait until button is released

If you find it difficult to move the mouse accurately, you could use
<Shift> <Alternate> <arrow> to move the mouse-cursor one pixel in the
desired direction. If you press <Insert> as well, you can "drag" something
accurately as if the left mouse-button was pressed.

You can find the maximal x- and y-coordinates of the mouse with :
     x=DPEEK(&H9862)
     y=DPEEK(&H9864)
But there's no guaranty you will find the coordinates there. Experiment
with XBIOS 0 for a more reliable method. Don't ask me how.

MOUSE returns negative coordinates if the mouse is to the left of or above
the current window (or the origin that has been selected with CLIP
OFFSET).


SETMOUSE

A mouseclick can be simulated with :
     SETMOUSE mx,my,mk
If you try this with an Alert-button you have to move the mouse after-
wards, or the button won't be selected. I don't know why, so I can't tell
if this is a bug.


DEFMOUSE

You can use one of the many Public Domain mouse-editors to design your own
mouse-mutant. But it's also easy to create a new mouse-cursor with the
Procedure Initio.mouse1 :
     PROCEDURE initio.mouse1
       ' *** global :  MOUSE1$
       RESTORE pattern.mouse1
       @make.mouse(mouse1$)
       pattern.mouse1:
       ' *** x,y,mode(0=normal;1=XOR),mask-colour,mouse-colour
       DATA 0,0,0,0,1
       ' *** mask-pattern (1 = pixel on , 0 = pixel off)
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       ' *** mouse-pattern
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
     RETURN
     '
     PROCEDURE make.mouse(VAR m$)
       LOCAL x,y,mode,msk.color,mouse.color,n,msk%,mouse%,msk.pat$
       LOCAL mouse.pat$,msk$,mouse$,pat$
       CLR msk.pat$,mouse.pat$,pat$
       READ x,y,mode,msk.color,mouse.color
       FOR n=1 TO 16
         READ msk$
         msk%=VAL("&X"+msk$)
         msk.pat$=msk.pat$+MKI$(msk%)
       NEXT n
       FOR n=1 TO 16
         READ mouse$
         LET mouse%=VAL("&X"+mouse$)
         LET mouse.pat$=mouse.pat$+MKI$(mouse%)
       NEXT n
       m$=MKI$(x)+MKI$(y)+MKI$(mode)+MKI$(color.index(msk.color))
       m$=m$+MKI$(color.index(mouse.color))+msk.pat$+mouse.pat$
     RETURN
The mask should be an exact copy of the mouse-pattern if you need a
transparant mouse. Leave the mask empty (all '0') and the mouse will
disappear behind objects on the screen. Fill the mask with '1' and the
16x16 mouse will always remain visible. Switch mask- and mouse-colour in
the first DATA-line to create a "reverse" mouse. Or use any VDI colour-
index that is available in the current resolution.


                              15.  JOYSTICK


STRIG and STICK

Here is an example of the use of STRIG and STICK if your joystick is
connected to Port 1 (your mouse is connected to Port 0) :
     STICK 1             ! joystick-mode (your mouse is now dead)
     REPEAT
       IF STRIG(1)
         joy=3
       ELSE
         joy=STICK(1)
       ENDIF
       ON joy GOSUB n,s,fire,w,nw,sw,dummy,e,ne,se
       PAUSE 5
       (...)
     UNTIL condition!
     STICK 0             ! back to mouse-mode
You need eight Procedures for the eight possible directions (see below)
and one Procedure for the Fire-button. The value 7 ('dummy') never occurs.
If you don't touch the joystick, the value of 'joy' will be 0, and this
means no Procedure will be called. A short pause is advisable, because
GFA-Basic is too fast.
                    5 1 9
                     \|/
directions :        4-0-8
                     /|\
                    6 2 10

If you desperately need an active mouse while using the joystick, you
could try the following "dirty" method :
     REPEAT
       IF MOUSEK=2
         joy=3
       ELSE
         joy=BYTE{&HE09}        ! for TOS-version 1.0 !!
       ENDIF
       ON joy GOSUB n,s,fire,w,nw,sw,dummy,e,ne,se
       PAUSE 5
     UNTIL condition!


                                16.  SOUND


SOUND and WAVE

After a SOUND-command, the sound sometimes continues in spite of the
elapsed time. If the command is followed by another SOUND- or a WAVE-
command, the time is handled correctly. This certainly sounds like a GFA-
bug.

The easiest way to stop all sound is :
     WAVE 0,0       ! turn all sound off

Sound of a certain frequency can be produced with :
     SOUND ch,vol,#ROUND(125000/freq%),pause

Although our ST is not famous for its brilliant sound, you can produce
nice sound-effects with the simple commands SOUND and WAVE. Check out the
Procedures Siren.sound, Tideli.sound, Bounce1.sound and Bounce2.sound to
hear what I mean.


Dosound (XBIOS 32)

XBIOS 32 (Dosound) can be used to play music in a special format. I
propose to use the extension 'X32' for song-files in this format. The
operating system takes care of playing the music during interrupts (every
1/50th second). Take a look at the Procedures Play.song and Stop.song to
see how you could use XBIOS 32 in your programs. You can even play a song
continuously with the Procedure Play.cont.song. Temporarily stopping a
song is possible with the Procedure Interrupt.song.

If you use XBIOS 32 to play music, you are advised to switch the key-click
off. Otherwise the music will stop as soon as the user presses a key.

Once I discovered XBIOS 32 did not work during the initialization (mainly
the filling of arrays) of a large program. I had converted the program
from GFA-Basic 2.0 to 3.0, but I did not have the patience to find out
what caused this problem.

XBIOS 32 can also be used for sound-effects. I have developed the
Procedure Initio.sound for building sound-strings from a few DATA-lines.
I hereby declare this as the standard method for creating sound-strings.
After @do.sound(sound$) you can hear the sound-effect. In the following
example the sound-string bounce3$ is created :
     PROCEDURE initio.sound
       ' *** commands in DATA-lines :
       ' ***         REG = 14 parameters for registers 0-13
       ' ***         END = end of sound-string
       ' ***         PAUSE = pause (followed by time in 1/50 seconds)
       ' ***         VAR = decrease/increase tone : channel,start,+/-step,
       ' ***                                                     end-value
       '
       bounce3.sound:
       DATA REG,0,0,0,0,0,0,27,248,16,16,16,35,95,0
       DATA VAR,3,255,-1,116
       DATA PAUSE,255,END
       RESTORE bounce3.sound
       @sound.string(bounce3$)
     RETURN
     '
     PROCEDURE sound.string(VAR s$)
       LOCAL n,snd$,snd,channel,begin,step,end
       s$=""
       DO
         READ snd$
         snd$=UPPER$(snd$)
         EXIT IF snd$="END"
         IF snd$="REG"
           FOR n=0 TO 13
             READ snd
             s$=s$+CHR$(n)+CHR$(snd)
           NEXT n
         ENDIF
         IF snd$="PAUSE"
           READ snd
           s$=s$+CHR$(130)+CHR$(snd)
         ENDIF
         IF snd$="VAR"
           READ channel,begin,step,end
           s$=s$+CHR$(128)+CHR$(begin)+CHR$(129)+CHR$(channel)+CHR$(step)
           s$=s$+CHR$(end)
         ENDIF
       LOOP
       s$=s$+CHR$(255)+CHR$(0)               ! terminator
     RETURN
     '
     PROCEDURE do.sound(sound$)
       VOID XBIOS(32,L:VARPTR(sound$))
     RETURN


Samples

From GFA-Basic you can surprise the user with a sampled sound. Examine the
Procedures Sample, Load.sample and Play.sample to see how. You'll have to
find suitable samples first. Look out for sound-effects and speech-
samples. Personally, I just love the famous Perfect-sample.


Speech

Your ST can talk to you with a little help (STSPEECH.TOS). My current GFA-
version (3.07) refuses to cooperate with the Procedures Initio.speech and
Talk, but I have included these anyway. Perhaps you can discover the bug.
In earlier versions both Procedures did work. A reset is necessary because
EXEC 3 is used.


Soundmachine

You can play songs, created with Soundmachine (TommySoftware), from GFA-
Basic. You'll need the Procedures Initio.soundmachine and Soundmachine,
and a song-file. You'll probably wonder if it's really your ST that's
playing the song. Soundmachine II is out, and looks even better. In this
new version you can choose between playing songs with samples, or without
samples (or samples for one of the three channels). You'll need the
Procedure Sm.initio or Msm.initio and several others. Try to find the
Public Domain demo-programs SAMSOUND.GFA, CHIPSND.GFA and SND_PLAY.GFA.
End of commercial, continue with text.


                          17.  PROGRAM DECISIONS


IF ... ENDIF

If the value of a certain variable must fall in the range min%-max%, you
could program that as follows :
     IF n%>max%
       n%=max%
     ENDIF
     IF n%<min%
       n%=min%
     ENDIF
In this case you could also use MAX and MIN :
     n%=MAX(MIN(n%,max%),min%)

You probably test for two conditions by using :
     IF cond1! AND cond2!
       (...)                  ! both true
     ENDIF
But separate testing is much faster :
     IF cond1!
       IF cond2!
         (...)                ! both true
       ENDIF
     ENDIF


SELECT

Multiple 'ELSE IF'-constructions can be replaced by a 'SELECT'-
construction. At each CASE you can use integers, strings or integer-
variables (not string-variables). Only the first four bytes of a string
can be used. The editor will not accept something like CASE "test2",
only CASE "test".



                            18.  PROGRAM LOOPS


Calculations

Try to remove all unnecessary calculations from loops, e.g. :
     FOR i=1 TO 1000
       x(i)=2*q*i
     NEXT i
It's a better idea to calculate 2*q outside the loop :
     q2=q*2
     FOR i=1 TO 1000
       x(i)=q2*i
     NEXT i

Always try to convert floating point variables to integers before entering
a loop. Then you will be able to use the fast integer-operators. An
obvious example would be a calculation with dollars (24.37) that could be
replaced by a calculation with cents (2437). Use this method if you know
the lowest possible value of the floating point variable (0.01 in this
case) and then divide by this value. But watch out for rounding errors and
integer-overflow.

Powers of 2 can be calculated fast by setting a bit :
     x%=BSET(0,6)   ! faster than x%=2^6
And for the ultimate speed-freaks, multiplying with a power of 2 is
slightly faster with SHL :
     y%=SHL(x%,3)   ! faster than y%=MUL(x%,8)
Of course there is no overflow-control if you use SHL (or MUL).

Sometimes, calculations in a loop can be replaced by a look-up table :
     FOR i=1 TO 1000
       y%(i)=x|(i)^2
     NEXT i
First, create a table of squares :
     DIM square%(255)
     FOR i=0 TO 255
       square%(i)=i*i
     NEXT i
Then use this table in the loop :
     FOR i=1 TO 1000
       y%(i)=square%(x|(i))
     NEXT i


FOR ... NEXT

I use local variables in Procedures if possible. But if you intend to
compile the program later, you should declare the counter in a FOR ...
NEXT loop as a global variable. In the compiled program, the loop will be
executed faster!

If you use floating point count-variables in a FOR ... NEXT loop (or any
other loop), you could encounter unexpected problems :
     FOR i#=0.1 TO 0.9 STEP 0.1
       PRINT i#
     NEXT i#
You would expect 0.9 as the result of the last addition (0.8 + 0.1), but
0.9 is never printed! This is not a bug in GFA-Basic, but caused by the
internal (binary) representation of floating point numbers. The last
addition results in a number slightly larger than 0.9 and therefore the
loop is left after printing 0.8 . If you insert the line
       i#=ROUND(i#,14)
in the loop, you can solve this problem. But the best solution is to avoid
floating point count-variables in loops. Integer count-variables are much
faster. You could easily change the loop to :
     FOR i=1 TO 9
       PRINT USING "#.#";i/10
     NEXT i
One more time: 'i' is a word-variable, because I use word-variables as
the default for number-variables without postfix.

If you use a floating point variable in a REPEAT UNTIL loop, you can avoid
the rounding error by using the special operator '==' :
     i#=0
     REPEAT
       i#=i#+0.1
       PRINT i#
     UNTIL i#==0.9
But you can't use the '=='-operator in a FOR ... NEXT loop.

In the following two examples a byte-variable is used as the counter :
     FOR i|=5 DOWNTO -1
       PRINT i|
     NEXT i|
     '
     FOR i|=250 TO 256
       PRINT i|
     NEXT i|
Of course, a byte-variable cannot have a value of -1 or 256. GFA does not
abort with an error-message, but skips the loops. Not a true bug perhaps,
but close.


Loops

Although you can use many different loops in GFA-Basic 3.0, there are
basically only two varieties. You can first test a condition, and then
either continue or leave the loop. Or you can first enter the loop, and
then test a condition to decide if you are going to continue or leave.

In an interpreted program the first choice is the fast FOR ... NEXT loop,
then the (slower) REPEAT ... UNTIL loop and finally the (slowest) WHILE
... WEND loop. In a compiled program all loops are executed equally fast!
If you use a DO ... LOOP, an EXIT IF condition will always take some extra
time.
Try to avoid a negative test in a loop, as this will take more time. E.g.
replace :
     WHILE NOT condition!
       (...)
     WEND
by the much faster :
     DO UNTIL condition!
       (...)
     LOOP
Or similarly replace :
     REPEAT
       (...)
     UNTIL NOT condition!
by the faster :
     DO
       (...)
     LOOP WHILE condition!

Finally, you could combine the test of one condition at the start of the
loop with the test of another condition at the end of the loop :
     DO UNTIL condition_1!
       (...)
     LOOP WHILE condition_2!


                           19.  PROGRAM CONTROL


GOSUB

A Procedure can be called in one of the following ways :
     GOSUB proc
     @proc
     proc
I prefer the second method, because this is spotted easily in a listing.
Also, the same method can be used to call a function.


ON BREAK GOSUB

You can't stop a program if a recursively called function is executed (?).

Use ON BREAK CONT to prevent calling the Break-Procedure twice. Nobody can
release the <Control> <Shift> <Alternate> keys fast enough :
     ON BREAK GOSUB break
     (...)
     PROCEDURE break
       ON BREAK CONT
       (...)
       ON BREAK GOSUB break
     RETURN
In this case the Break-Procedure is activated again before leaving the
Procedure. Study the Standard Procedure Break (in one of the STANxxxx.LST-
files) for an example of this method.


ERROR

You can simulate ERRORs with values from -127 to 127. For GFA-errors use
values from 0 to 93, for bomb-errors 102 (2 bombs) to 109 (9 bombs) and
for TOS-errors -1 to -67.


EVERY and AFTER

It's not possible to use EVERY and AFTER at the same time. Both commands
don't work during a long PAUSE or DELAY (or any other command that takes a
lot of time). You can only call Procedures without parameters. Don't make
the Procedure too long, or it may be called while being processed!

In a compiled program you have to incorporate '$I+ U+', or EVERY and AFTER
can't be used.


GOTO

You can't use GOTO in a Procedure, a Function or a FOR ... NEXT loop.


DELAY

The DELAY-command does not operate correctly in version 3.07 of GFA-Basic.
During DELAY a Break is impossible. A nastier bug is the appearance of the
mouse-cursor during DELAY, even after HIDEM. You are advised to use PAUSE
instead.


CHAIN

In GFA-Basic all variables and arrays are lost after CHAINing the next
program. However, you could use the 160-byte buffer of the scrap-library
to pass a short message to the next program :
     buffer$=SPACE$(160)           ! 160 bytes maximum ??
     message$="this message was sent by the previous program"
     message$=message$+CHR$(0)
     LSET buffer$=message$
     r%=SCRP_WRITE(buffer$)        ! r%=0 if error
     CHAIN file$
Read the message with :
     buffer$=SPACE$(160)
     r%=SCRP_READ(buffer$)
     message$=CHAR{V:buffer$}
The use of this buffer is completely illegal, but who cares if you don't
use a scrap-library? Unfortunately the GFA-editor seems to think so too,
so you should experiment a little before trusting this method.


EXEC

If you are going to run another program more than once, you'll have to use
EXEC 3 :
     base%=EXEC(3,file$,"","")          ! load, but don't start yet
     base$=STR$(base%)
     cmdl$=CHR$(LEN(base$)+1)+base$     ! create command line
     (...)
     r%=EXEC(4,"",cmdl$,"")             ! now run it
The variable r% contains a value returned by the program (or -39 if not
enough memory was available). Repeat the last line if you want to run the
loaded program again. Of course you should use EXEC 0 if you're going to
run the program one time only. Read the paragraph 'RESERVE' if you are
going to use EXEC 3.

If you call a '*.PRG'-program with EXEC 0, you pass the null-string ("")
as the command-line. You need the command-line only if you call a '*.TTP'-
program. The command-line is converted to upper case and can't exceed 125
bytes. The first byte of the command-line (usually) determines the length
of the line, so the command-line can't contain more than 124 characters.
You can use this in a TTP-program (compiled GFA-Basic program, extension
changed to TTP), but it's easier to read the command-line with :
     cmdl$=CHAR{BASEPAGE+&H81}


                              20.  GRAPHICS


SETCOLOR and VSETCOLOR

With commands like COLOR, DEFTEXT, DEFFILL, etc., you use a VDI colour-
index. Unfortunately SETCOLOR uses a different table :
     VDI colour-index    : 0  1  2  3  4  5  6  7  8  9 10 11 12 13 14 15
     SETCOLOR (Low rez)  : 0 15  1  2  4  6  3  5  7  8  9 10 12 14 11 13
     SETCOLOR (Med rez)  : 0  3  1  2
From this table it follows you would have to use 'SETCOLOR 2,r,g,b' to
change colour-index 3. By the way, all Line-A commands use the SETCOLOR-
table as well! This is not a "bug", but a consequence of two different
colour-tables that are used by GEMDOS and GEM. You are advised to use :
     VSETCOLOR index,r,g,b
This index is exactly the same as the colour-index, so you would use
'VSETCOLOR 2,r,g,b' in order to change colour-index 2. If you like, you
could use the hexadecimal 3-byte mix-value :
     VSETCOLOR index,&Hrgb
But you won't like it at all, because this doesn't work properly. GFA-
Basic swaps the r- and g-byte, so you would have to use :
     VSETCOLOR index,&Hbgr
Better avoid this method, or you'll experience colour-changes if GFA
corrects this bug in a future version.

In High resolution you can invert the screen-colours with :
     VSETCOLOR 0,0       ! reverse High-screen (black background)
     VSETCOLOR 1,0       ! normal High-screen (black letters)
An inverted screen is perhaps slightly less suitable for text, but
graphics look superb.

Colour-index 0 determines the colour of the background in Low and Medium
resolution. This index also determines the colour of the border on your
screen. You can change this colour, although you can't draw or PRINT on
the screen-border of your colour monitor. The colour of all PRINTed text
is determined by colour-index 1, unless you use the 'Esc b' command (read
the paragraph 'PRINT' again if your long-term memory is too short) :
     VSETCOLOR 0,r,g,b   ! change colour of background
     VSETCOLOR 1,r,g,b   ! change colour of all PRINTed text


Palette

Before changing colours, you should always save the current palette. And
do restore the old palette before the user exits the program. I hate
programs that return to a pink or yellow desktop. You can store the
palette either in an integer array or in a string, using XBIOS 7
(Setcolor) :

     PROCEDURE save.palette
       LOCAL i
       ERASE old.palette%()
       DIM old.palette%(15)
       FOR i=0 TO 15
         old.palette%(i)=XBIOS(7,i,-1)
       NEXT i
     RETURN
     '
     PROCEDURE make.palette.string(VAR pal$)
       LOCAL n
       pal$=""
       FOR n=0 TO 15
         pal$=pal$+MKI$(XBIOS(7,n,-1))
      NEXT n
     RETURN
The string-method is compatible with Degas. Restore the old palette with
the corresponding Procedures :
     PROCEDURE restore.palette
       LOCAL i
       FOR i=0 TO 15
         VOID XBIOS(7,i,old.palette%(i))
       NEXT i
     RETURN
     '
     PROCEDURE change.palette(pal.string$)
       VOID XBIOS(6,L:VARPTR(pal.string$))
     RETURN
You could also use the Standard Procedure Standard.low.colors or
Standard.med.colors to restore the default palette. You can find these
Procedures in the STANxxxx.LST-files.

You can examine the rgb-value of a certain VDI colour-index with :
     PROCEDURE rgb.value(index,VAR rgb$)
       LOCAL col%
       col%=XBIOS(7,color.index(index),-1)
       rgb$=RIGHT$(HEX$(col%),3)
     RETURN
The Standard Array color.index() is used to convert the VDI colour-index.

A completely new palette for Medium resolution can be installed with :
     PROCEDURE new.med.colors
       LOCAL n,r,g,b,col$
       RESTORE med.new.col.data
       FOR n=0 TO 3
         READ col$
         r=VAL(LEFT$(col$))
         g=VAL(MID$(col$,2,1))
         b=VAL(RIGHT$(col$))
         VSETCOLOR n,r,g,b
       NEXT n
       med.new.col.data
       DATA 000,000,000,000
     RETURN
You can show the current palette on the screen with the Procedure
Palette.box :
     PROCEDURE palette.box(x,y,h,w)
       ' *** left upper corner of rectangle at x,y
       ' *** rectangle-height h; width of one colour-box w
       LOCAL arect.fill,fill.adr%,i,x1,x2
       x2=x+16*w+2
       COLOR black
       BOX x,y,x2,y+h
       arect.fill=-1
       f%=V:arect.fill
       IF low.res!
         FOR i=0 TO 15
           x1=ADD(SUCC(x),MUL(i,w))
           ARECT x1,SUCC(y),ADD(x1,w),PRED(ADD(y,h)),color.index(i),0,f%,0
         NEXT i
       ELSE IF med.res!
         FOR i=0 TO 3
           x1=ADD(SUCC(x),MUL(i,w))
           ARECT x1,SUCC(y),ADD(x1,w),PRED(ADD(y,h)),color.index(i),0,f%,0
         NEXT i
       ENDIF
     RETURN

You can darken the screen by dimming all colours simultaneously with the
Procedure Dim.colors :
     PROCEDURE dim.colors(reg1,reg2,val)
       ' *** dim colours from VDI colour-index reg1 to reg2 with val
       ' *** for val=1 colour 254 (rgb) will become 143
       LOCAL i,r,g,b
       FOR i=reg1 TO reg2
         @rgb.value(i,rgb$)
         r=MAX(PRED(VAL(LEFT$(rgb$))),0)
         g=MAX(PRED(VAL(MID$(rgb$,2,1))),0)
         b=MAX(PRED(VAL(RIGHT$(rgb$))),0)
         VSETCOLOR i,r,g,b
       NEXT i
     RETURN

Nothing is impossible in GFA-Basic, even colour-cycling is easy with
EVERY in the Procedure Color.cycle :
     PROCEDURE color.cycle(reg1,reg2,time)
       ' *** cycles colours from VDI colour-index reg1 to reg2
       ' *** global :  COLOR.CYCLE!  COL.REG1  COL.REG2
       IF NOT color.cycle!
         col.reg1=reg1
         col.reg2=reg2
         color.cycle!=TRUE
         EVERY time GOSUB cycle.once
       ELSE
         color.cycle!=FALSE
         EVERY STOP
       ENDIF
     RETURN
     '
     PROCEDURE cycle.once
       LOCAL col1%,col2%
       col1%=XBIOS(7,color.index(col.reg2),-1)
       FOR reg=col.reg1 TO PRED(col.reg2)
         col2%=XBIOS(7,color.index(reg),-1)
         ~XBIOS(7,color.index(reg),col1%)
         SWAP col1%,col2%
       NEXT reg
       ~XBIOS(7,color.index(col.reg2),col1%)
     RETURN
Call the Procedure Color.cycle again to stop the colour-cycling.


DEFMARK

The point as mark-symbol (No. 1) cannot be enlarged. Other mark-symbols
can be enlarged, but all lines in the symbol retain a width of one pixel.
The size of a symbol must be a multiple of 11 plus 6: 0, 17, 28, 39, 50.
For a value in between, the prior allowed size is chosen. Perhaps there is
some magic hidden in the allowed sizes, or am I missing something?


DEFFILL

If you haven't defined your own Fill-pattern, the Atari-symbol will be
used after DEFFILL 1,4,x. The desktop Fill-pattern is DEFFILL 1,2,4.

The Fill-pattern string can consist of 16, 32 or 64 words (MKI$-format).
Word 1 to 16 is needed for bitplane 0 (High resolution), word 17 to 32 for
bitplane 1 (Medium resolution) and word 33 to 64 for the bitplanes 2 and 3
(Low resolution). In all resolutions, the pattern occupies a rectangle of
16x16 pixels on the screen. The same 16x16 rectangle is also used for the
mouse-cursor and sprites. You can always use a Fill-pattern in a lower
resolution, e.g. a High-pattern in Medium or Low resolution, but not the
other way around. Examine the three Procedures Initio.high.fill1,
Initio.med.fill1 and Initio.low.fill1 to see how easy you can design your
own Fill-patterns. There's gold in them thar Fills. You could surprise the
user with a bomb-pattern :
     PROCEDURE initio.bomb.fill
       ' *** global :  BOMB.FILL$
       RESTORE bomb.fill
       @make.high.fill(bomb.fill$)
       bomb.fill:
       DATA 0000011000000000
       DATA 0010100100000000
       DATA 0000000010000000
       DATA 0100100001000000
       DATA 0001000111110000
       DATA 0000000111110000
       DATA 0000011111111100
       DATA 0000111111111110
       DATA 0000110111111110
       DATA 0001111111111111
       DATA 0001111111101111
       DATA 0000111111101110
       DATA 0000111111011110
       DATA 0000011111111100
       DATA 0000001111111000
       DATA 0000000011100000
     RETURN
     '
     PROCEDURE make.high.fill(VAR fill$)
       LOCAL i,pat$,pat%
       CLR fill$
       FOR i=1 TO 16
         READ pat$
         pat%=VAL("&X"+pat$)
         fill$=fill$+MKI$(pat%)
       NEXT i
     RETURN

Be careful, a screen filled with this pattern might provoke a heart-
attack. If it doesn't, you could try the following dirty trick (High
resolution only) with the Procedures Busy and Achtung :
     @busy          ! looks like the computer is very busy
     ~INP(2)        ! but nothing happens, until the user presses a key...
     @achtung
     PAUSE 500
     CLS
     PRINT " Thank you for your patience, I'm not busy anymore ..."
     PAUSE 150

Many Fill-patterns are available as files. You can use these with
something like Procedure Initio.fill1 :
     PROCEDURE initio.fill1(VAR pattern$)
       LOCAL bytes
       bytes=32         ! 32 bytes for High resolution
       ' *** load Fill-pattern (32 bytes for High resolution) here
       INLINE fill1%,32
       pattern$=STRING$(bytes,0)
       BMOVE fill1%,V:pattern$,bytes
       DEFFILL ,pattern$
     RETURN

FILLing a screen with a pattern takes some time, especially in High
resolution. Use the following method for almost immediate filling of the
entire High resolution screen :
     PROCEDURE full.fill(fill%)
       ACLIP 1,0,0,639,399
       ARECT 0,0,639,399,1,0,fill%,15
       ACLIP 0,0,0,639,399
     RETURN
Fill% is the address of a FILL-pattern (32 bytes). This very fast
alternative Fill-method works in High resolution only.


DEFLINE

After 'DEFLINE ,n' all horizontal lines have a width of n pixels (n should
be odd), except in Medium resolution. But if n is larger than 1, all
vertical lines are n+2 pixels wide! I have trouble counting the pixels
in Medium resolution. I think the width of horizontal lines is :
         n :   1 3 5 7 9
     width :   1 1 3 3 5 etc.
Is this documented anywhere?

You define your own Line-patterns by using a negative 16-bit value (from
-&X1 to -&X1111111111111111). Each set bit corresponds with a pixel in the
Line-pattern (High resolution). The highest bit (15) corresponds with the
leftmost pixel of the pattern. Don't get confused if the editor changes
the negative binary number you entered as a pattern. The editor uses a
special notation for negative binary numbers.

GFA-Basic represents integer numbers as binary strings of 32 bits. The
most significant bit (31) determines the sign of the integer. If this bit
is 0, the remaining 31 bits represent an "ordinary" positive number. But
if the most significant bit is 1, the remainder is a negative number in
'two's complement' notation. I won't try to explain that. In any case, the
next time you type -&X111 and a friend is watching you, don't blink your
eyes, but casually remark "of course the editor converts this into two's
complement notation". That's also the reason GFA-Basic can work with
integers from -(2^31) to +(2^31)-1.


DEFTEXT

In some publications you can read about 'shadowed text' (style = 32), but
unfortunately our GEM doesn't know this style. You can even find the mask
for shadowed text with WORD{L~A+92}, but it's 0.

I never succeeded in finding the current text-style with VDISYS 38
(vqt_attributes). Either a bug in GEM or my mistake. I don't want to know,
because the easy way is :
     txt.style=WORD{L~A+90}
This could be important if you intend to use DEFTEXT in a Procedure, but
would like to restore the original DEFTEXT-settings before leaving the
Procedure.

With DEFTEXT you can set the height of TEXT-letters. A letter occupies
more space though, determined by the letter-box :

     letter-height  letter-box     system-font
           4          6 x 6        icon
           6          8 x 8        Medium & Low rez
          13          8 x 16       High resolution

The letter-height is the distance from Descent-Line to Ascent-Line, but
the Bottom-Line and Top-Line lie at least one pixel lower/higher. The
height of the letter-box is the distance from Bottom-Line to Top-Line.

Most letters rest on the Base-Line, but letters with a descender (g,j,p,
etc.) rest on the Descent-Line. If you are still with me, from top to
bottom we have the following lines :
     Top-Line
     Ascent-Line
     Base-Line
     Descent-Line
     Bottom-Line
Drop me a line if you don't understand this.


GRAPHMODE

If you draw a rectangle with BOX in GRAPHMODE 3 (Xor-mode), the pixel in
the left upper corner is not drawn. Actually this pixel is drawn twice,
and in GRAPHMODE 3 this means the pixel disappears. Use PLOT to draw this
pixel :
     GRAPHMODE 3
     BOX x1,y1,x2,y2
     PLOT x1,y1          ! and fill the gap

With PBOX in GRAPHMODE 3 you'll also get trouble in the same corner. Avoid
this by using the command 'BOUNDARY 0' first :
     GRAPHMODE 3
     BOUNDARY 0
     PBOX 50,50,100,100

GRAPHMODE 3 is especially useful if you make a temporary drawing. Draw the
same picture a second time to restore the original screen. Examine Proce-
dures like Rubber.line, Draw.box and Drag.box for examples of this method.
The Procedure Rubber.line is used to draw a line from (x,y) to the mouse-
cursor :
     PROCEDURE rubber.line(x,y,VAR x2,y2)
       LOCAL x1,y1,x2,y2,k
       GRAPHMODE 3
       DEFMOUSE 3
       SHOWM
       MOUSE x1,y1,k
       REPEAT                           ! main loop
         LINE x,y,x1,y1                 ! draw line
         REPEAT
           MOUSE x2,y2,k
         UNTIL x2<>x1 OR y2<>y1 OR k>0  ! mouse moved
         LINE x,y,x1,y1                 ! undraw line
         x1=x2
         y1=y2
       UNTIL k>0         ! mouse-click : ready (x2 and y2 returned)
       GRAPHMODE 1
       LINE x,y,x2,y2    ! this is it
       HIDEM
       DEFMOUSE 0
       PAUSE 10
     RETURN

You could also use the 'GRAPHMODE 3'-method for animation, but the XBIOS 5
(Setscreen) method is more suitable.

Don't try to draw in GRAPHMODE 3 with a linewidth greater than 1 pixel.
GEM will surprise you with some modern art if you can't resist the
temptation.

If you want to confirm a particular choice of the user, you can invert the
relevant part of the screen with the Procedure Invert.block. Call this
Procedure again with the same parameters to restore the original screen :
     PROCEDURE invert.block(x1,y1,x2,y2,color)
       GRAPHMODE 3
       DEFFILL color,1
       BOUNDARY 0
       PBOX x1,y1,x2,y2
       BOUNDARY 1
       GRAPHMODE 1
     RETURN

You can 'grey out' an unavailable option on the screen with :
     PROCEDURE block.dimmer(x1,y1,x2,y2,color)
       GRAPHMODE 3
       DEFFILL color,2,2
       BOUNDARY 0
       PBOX x1,y1,x2,y2
       BOUNDARY 1
       GRAPHMODE 1
     RETURN
Call this Procedure again to restore the screen.

The entire (High resolution) screen can be dimmed with :
     PROCEDURE screen.dimmer
       ' *** global :   DIMMER.SCREEN$   DIMMER.SWITCH!
       IF dimmer.switch!
         SPUT dimmer.screen$
         dimmer.switch!=FALSE
       ELSE
         SGET dimmer.screen$
         GRAPHMODE 4
         DEFFILL 1,2,4
         PBOX 0,0,639,399
         dimmer.switch!=TRUE
       ENDIF
     RETURN
The screen will be restored if you call the Procedure again.


PLOT and DRAW

You can use both 'PLOT x,y' and 'DRAW x,y' to set a point on the screen.
The size of the point can be changed :
     DEFLINE ,size,2,2   ! change size of points
But the shapes you'll see don't look like points anymore, due to the same
problem as described in the paragraph 'DEFLINE'. Use PCIRCLE for proper
fat points.


PCIRCLE

With CLIP on, a PCIRCLE touching the upper screen-border is not filled
properly in High resolution :
     CLIP 0,0,640,400
     PCIRCLE 0,0,50
I don't know if we should blame GFA or GEM for not filling the two top-
lines in the circle.


CURVE

With the command CURVE you can draw a Bezier-curve :
     CURVE x1,y1,x2,y2,x3,y3,x4,y4
The Bezier-curve starts at (x1,y1) and ends at (x4,y4). The other two
points act like little magnets. You can also use this command to draw a
'normal' curve between two points by letting the points (x3,y3) and
(x4,y4) coincide. Try the following to see what I mean :
     GRAPHMODE 3
     MOUSE x2,y2,k
     DO
       CURVE 10,100,x2,y2,110,100,110,100    ! draw curve
       REPEAT
         MOUSE x,y,k
       UNTIL x<>x2 OR y<>y2
       CURVE 10,100,x2,y2,110,100,110,100    ! erase curve
       x2=x
       y2=y
     LOOP
This method could be used to draw large letters.


TEXT

The coordinates used with TEXT determine the start of the Base-Line of the
text. The descenders of letters like 'g', 'j', and 'p' lie below the Base-
Line. This is especially important, not to say frustrating, if you use
TEXT with an angle of 90, 180 or 270 degrees. The text rotates anticlock-
wise around the TEXT-coordinates!

If you intend to combine PRINTed text with TEXT, you probably will like
the Procedure Text.at as the analogue of 'PRINT AT' :
     PROCEDURE text.at(c,l,t$)
      TEXT (c-1)*char.width,l*char.height+3*high.res!+2*(NOT high.res!),t$
     RETURN

You can use TEXT to print "digital" numbers (ASCII-code 16-25) :
     FUNCTION digital$(number$)
       LOCAL dig$,i
       CLR dig$
       FOR i=1 TO LEN(number$)
         dig$=dig$+CHR$(BCLR(ASC(MID$(number$,i,1)),5))
       NEXT i
       RETURN dig$
     ENDFUNC
Use this Function as follows :
     TEXT x,y,@digital$("1237")


SPRITE

You could design and save sprites in vitro with one of the many Sprite-
editors that are available. Or you can use something like the Procedure
Initio.sprite1 to create a sprite in vivo. Compare this Procedure also
with the Procedure Initio.mouse1 :
     PROCEDURE initio.sprite1
       ' *** global :  SPRITE1$
       RESTORE pattern.sprite1
       @make.sprite(sprite1$)
       pattern.sprite1:
       ' *** x,y,mode(0=normal;1=XOR),mask-colour,sprite-colour
       DATA 0,0,0,0,1
       ' *** mask-pattern (1 = pixel on , 0 = pixel off)
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       ' *** sprite-pattern
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
       DATA 0000000000000000
     RETURN
     '
     PROCEDURE make.sprite(VAR s$)
       LOCAL x,y,mode,msk.color,spr.color,n,msk%,spr%,msk.pat$,spr.pat$
       LOCAL msk$,spr$,pat$
       CLR msk.pat$,spr.pat$,pat$
       READ x,y,mode,msk.color,spr.color
       FOR n=1 TO 16
         READ msk$
         msk%=VAL("&X"+msk$)
         msk.pat$=msk.pat$+MKI$(msk%)
      NEXT n
       FOR n=1 TO 16
         READ spr$
         spr%=VAL("&X"+spr$)
         spr.pat$=spr.pat$+MKI$(spr%)
       NEXT n
       FOR n=1 TO 16
         pat$=pat$+MID$(msk.pat$,n*2-1,2)+MID$(spr.pat$,n*2-1,2)
       NEXT n
       s$=MKI$(x)+MKI$(y)+MKI$(mode)+MKI$(color.index(msk.color))
       s$=s$+MKI$(color.index(spr.color))+pat$
     RETURN
The mask should be an exact copy of the sprite-pattern if you need a
transparant sprite. Leave the mask empty (all '0') and the sprite will
disappear behind objects on the screen. Fill the mask with '1' and the
16x16 sprite will always remain visible. Switch mask- and sprite-colour in
the first DATA-line to create a "reverse" sprite. Or use any VDI colour-
index that is available in the current resolution.

If you put a sprite on the screen, the background (16x16 pixels) is
temporarily saved. Using more than one sprite simultaneously, it is
essential you remove sprites in reverse order. This is necessary because a
sprite could overlap another sprite. Removing the top sprite first ensures
that the original background will reappear after removing the first
sprite, e.g. :

     DO
       (...)
       SPRITE s2$        ! remove sprites...
       SPRITE s1$
       VSYNC             ! prevents blinking, but slows down
       SPRITE s1$,x1,y1  ! draw sprites...
       SPRITE s2$,x2,y2
       (...)
     LOOP


VQT_EXTENT

The function VQT_EXTENT can be used if you would like to draw a rectangle
around a text-string :
     ~VQT_EXTENT(txt$,x1,y1,x2,y2,x3,y3,x4,y4)
The coordinates of the four corners depend on the angle of the text (0,
90, 180 or 270 degrees) and of course on the size of the text. The point
(x1,y1) is the lower left corner of the imaginary rectangle around the
text and the other points are arranged anticlockwise around the text-
string. Because the text rotates around the TEXT-coordinates (start of the
Base-Line), it will take some trial and error to determine the correct
position of the rectangle if the angle is not 0 degrees. In the following
table you'll find the "true" origin of the rectangle, the width and the
height of the rectangle, and also the actual position of the lower left
corner of the text-block (x1,y1) :
     angle     position (x1,y1)    origin    width     height
        0         lower left        x1,y1     x2         y4
      900         lower right       x4,y4     x1         y3
     1800         upper right       x3,y3     x4         y2
     2700         upper left        x2,y2     x3         x4
The coordinates of the origin are (0,0), so with an angle of 0 degrees
both x1 and y1 are 0. The rectangle rests on the x-axis, while the left
side coincides with the y-axis. This is a "mathematical" y-axis, not a
"screen" y-axis. This means you go upwards for positive y-values. For an
angle of 0 degrees the coordinates will be :
     (x4,y4).           .(x3,y3)
            . TEXTBLOCK .
     (x1,y1)             (x2,y2)

If you understand the table, you should be surprised by the height 'x4'
instead of 'y1' at an angle of 270 degrees. I think I discovered a bug in
GEM here. Correct GEM by changing the following variables if an angle of
270 degrees is used :
     y1=x4
     SWAP x4,y4
Now, the height is 'y1' as you suspected. Clever, aren't we? I have not
been able to confirm my discovery. None of my reference-books mention the
bug.


Line-A

The Line-A commands are faster than the corresponding VDI-commands in GFA-
Basic. The difference should be even greater after loading GDOS (?). In
the following table you can find how many times faster the Line-A command
is :
      PSET / PLOT  = 3
      PTST / POINT = 2
     HLINE / LINE  = 2
     ARECT / PBOX  = 1.5
The syntax of Line-A commands is more complicated, but that's no problem
for us GFA-experts. Line-A commands use the 'SETCOLOR-index', so you'll
probably need the Standard Array color.index().

HLINE

An additional advantage of the commands HLINE, ARECT and APOLY is that you
don't have to change the DEFFILL-parameters in the main program. For solid
horizontal lines, use :
     pattern=-1
     adr%=V:pattern
     HLINE x1,y,x2,color,mode,adr%,0
You can't use &X1111111111111111 (16 bits) for the pattern, because bit 15
of a word-variable is a flag for a negative number. Yes, that's why the
largest positive word is 2^15 - 1 (32767). The solution to this little
problem is to assign -1 to the word-variable. You have my word, now all 16
bits are 1. Use BIN$ if you don't believe me.

For very complicated patterns you could use a word-array :
     DIM pattern(i)
     adr%=V:pattern(0)
     (...)               ! put fill-pattern in pattern(0) to pattern(i)
     HLINE x1,y,x2,color,mode,adr%,i


ACHAR and ATEXT

It's difficult to combine the Line-A commands ACHAR and ATEXT with TEXT.
The coordinates used with ACHAR and ATEXT determine the position of the
left upper corner of the (first) letter-box. That's the Top-Line, not the
Base-Line.

You can't use the text-style underlined (8) with ACHAR and ATEXT. Probably
a GFA-bug.


GET and PUT

You could save a rectangular part of the screen as follows :
     GET x1,y1,x2,y2,pic$
     BSAVE file$,V:pic$,LEN(pic$)  ! use the extension PUT in the filename

Later, you could put the saved picture back on the screen with :
     OPEN "I",#1,file$
     LET bytes%=LOF(#1)            ! how many bytes needed?
     CLOSE #1
     picture$=SPACE$(bytes%)       ! reserve some space,
     BLOAD file$,V:picture$        ! load the picture
     PUT x,y,picture$              ! and look at it

The Procedures Message, Warning, Message.on and Message.off use GET and
PUT to save and later restore the part of the screen that is used for
text.

A GET-string starts with three words for width, height and number of
bitplanes. The number of bitplanes is determined by the resolution: 1 for
High, 2 for Medium and 4 for Low. After these three words follows the
actual picture as a list of words. As the picture-width is not necessarily
a multiple of 16, any bits beyond the right border will be ignored by the
PUT-command.

Here is the connection between GRAPHMODE and PUT-mode :
     GRAPHMODE      PUT-mode
         1             3 (default)
         2             7
         3             6
         4            13

I have encountered a few programs in GFA-Basic 2.0 where PUT was used
just outside the screen. In GFA-Basic 3.0 the program didn't work. The
same occurred in a program where a picture was BLOADed a few bytes before
the screen-RAM. I don't understand why GFA-Basic 3.0 doesn't accept this,
as there is some unused space there (read the paragraph 'RAM'), but I've
learned to correct this when I convert a program from GFA-Basic 2.0 to
version 3.0.


Degas-Pictures

A Degas picture-file contains not only the actual picture (same format as
SGET-picture), but also the colour-palette. Use the Procedure Show.degas
to load and show a Degas-picture :
     PROCEDURE show.degas(degas$)
       LOCAL degas.picture$,degas.picture%,degas.palette$
       LOCAL degas.palette%
         degas.picture$=SPACE$(32000)
         degas.picture%=VARPTR(degas.picture$)
         degas.palette$=SPACE$(32)
         degas.palette%=VARPTR(degas.palette$)
         OPEN "I",#90,degas$
         SEEK #90,2                            ! skip resolution
         BGET #90,degas.palette%,32            ! load palette of picture
         SEEK #90,34
         BGET #90,degas.picture%,32000         ! load actual picture
         CLOSE #90
         ~XBIOS(6,L:degas.palette%)            ! change palette
         SPUT degas.picture$                   ! show the picture
     RETURN

The original Degas-files have a length of 32034 bytes :
     1 word         - resolution
     16 words       - palette
     16000 words    - picture data
You can use BTST to check the resolution (bit 0 = Low, bit 1 = Medium, bit
2 = High), but you could also look at the extension of the filename
(PI1/PI2/PI3 for Low/Medium/High). In the second Degas-version (Degas
Elite), 16 words for "colour-animation" can be added after the picture
data.
A Degas Elite picture can (and really should!) be saved in a compressed
format. The extensions PC1/PC2/PC3 are used for Low/Medium/High
resolution. Also, the highest bit of the resolution-word is set as a flag
for a compressed picture. With the Procedure Show.comp.degas you can load
and show a compressed Degas-picture.


Neochrome-Pictures

Sometimes the "Neochrome"-format is used for pictures (32128 bytes) :
     1 integer           - resolution (0/1/2 for Low/Medium/High)
     16 words            - palette
     12 bytes            - filename (nnnnnnnn.eee)
     4 bytes + 1 word    - colour animation data
     18 integers         - reserved
     16000 words         - picture data


VSYNC

The VSYNC-command is useful if you want to prevent irritating blinking
during animation. Always VSYNC before drawing a new picture in an
animation sequence (including SPRITE-animation). The program is slowed
down of course, because it waits for a vertical blank interrupt before
starting to draw. But it looks much nicer.


Scroll

With BMOVE and RC_COPY you can accomplish pretty smooth scrolling. GET/PUT
is too slow, and only works on the logical screen. BITBLT is more
flexible, but also more complicated. And not faster (?). Study the
Procedures Scroll.up and Scroll.down to see how you could scroll the
entire screen up or down :

     PROCEDURE scroll.up(scroll.lines,scroll.color)
       LOCAL n,bytes,move.bytes,source%
       IF high.res!
         LET bytes=80*scroll.lines
       ELSE
         LET bytes=160*scroll.lines
       ENDIF
       move.bytes=32000-bytes
       source%=physbase%+bytes
       VSYNC
       BMOVE source%,physbase%,move.bytes
       DEFFILL scroll.color
       PBOX 0,scrn.y.max-scroll.lines+1,scrn.x.max,scrn.y.max
       FOR n=1 TO DIV(scrn.y.max,scroll.lines)
         VSYNC
         BMOVE source%,physbase%,move.bytes
       NEXT n
     RETURN
Can anybody explain the interference lines that sometimes appear during
the scrolling?

Several fade-over effects can be found in the Procedures Up.scroll,
Slider.scroll, etc. Most Procedures can only be used in High resolution.

For scrolling of one or more text-lines you could use the Procedures
Scroll.text.up and Scroll.text.down :
     PROCEDURE scroll.text.up(begin,end)
       LOCAL screen%,sx,sy,w,h,dx,dy
       IF begin>1 AND end>=begin
         screen%=XBIOS(3)          ! logical screen
         sx=0
         sy=(begin-1)*char.height
         w=scrn.x.max
         h=(end-begin+1)*char.height
         dx=0
         dy=sy-char.height
         RC_COPY screen%,sx,sy,w,h TO screen%,dx,dy
       ELSE
         PRINT bel$;
       ENDIF
     RETURN
This method is also used in the Procedure Debug.


ACLIP

Line-A commands are 'CLIP-sensitive', so you should always use an appro-
priate ACLIP-command before a Line-A command. The following Line-A
commands are not influenced by ACLIP : ALINE, HLINE, PSET, PTST and
BITBLT.


Blitter

The Blitter-TOS (1987) allows you to switch the Blitter on/off. I couldn't
test the following Procedure, because I don't have a Blitter. But if I
understand the function XBIOS 64 (Blitmode) correctly, you could switch
the Blitter on and off from GFA-Basic :
     PROCEDURE blitter(switch!)
       LOCAL status
       status=XBIOS(64,-1)
       IF BTST(status,1)           ! Blitter available?
         IF switch!
           status=BSET(status,0)   ! Blitter on
         ELSE
           status=BCLR(status,0)   ! Blitter off
         ENDIF
         ~XBIOS(64,status)         ! do it
       ENDIF
     RETURN

By the way, Line A commands do not use the Blitter. The Blitter-chip
contains a hardware-routine that replaces the Line A BitBlt-function
(BITBLT in GFA-Basic). All Mega ST's have a Blitter installed.


                               21.  EVENTS


MENU()

There is no easy way to test in a program if an accessory has been
selected by the user. MENU(1) looks promising, but the value 40 (select
accessory) or 41 (close accessory) is only sent to the accessory! It
would have been nice to be able to determine if an accessory has been
closed, because GEM will clear the accessory-window and will fill the
space with the desktop-pattern. No easy solution for this one, sorry. The
best idea probably is to test frequently with 'IF MENU(1)=20' if a redraw
is necessary, e.g. :
     ON MENU MESSAGE GOSUB redraw
     (...)
     PROCEDURE redraw
       IF MENU(1)=20
         (...)           ! redraw screen
       ENDIF
     RETURN
This method only works if you have opened a window.


ON MENU BUTTON

The syntax for ON MENU BUTTON is :
     ON MENU BUTTON clicks,button,event GOSUB proc
For both 'button' and 'event' you can use the numbers 0-3. The variable
'clicks' stands for the maximal number of clicks you want to register. If
you choose '2', the Procedure will be called if the user clicks once or
twice :
     ON MENU BUTTON 2,1,1 GOSUB proc
It's not possible to wait for a double-click, unless the progam is really
waiting, and not doing anything else :
     SELECT EVNT_BUTTON(2,1,1)
     CASE 1
       ' clicked once
     CASE 2
       ' clicked twice
     ENDSELECT
But you can't combine this with an ON MENU loop.

If you use the described method :
     ON MENU BUTTON 2,1,1 GOSUB proc
you could use MENU(15) in the called Procedure to check if the user
clicked twice. The same Procedure would be called after a single click,
but you could ignore that. Fasten your seatbelts now. If you run such a
program the first time, a double click is not registered in MENU(15). If
you suspect a bug and run the program again, MENU(15) works all right.
Nasty.

Another bug, but this time a GEM-bug (I think), after :
     ON MENU BUTTON 1,2,2 GOSUB proc
The Procedure is called immediately, whether the right mouse-button was
pressed or not.

If you want to switch ON MENU BUTTON temporarily off, use :
     ON MENU BUTTON clicks,button,event GOSUB dummy
The Procedure Dummy should be empty. Use the same method to switch other
ON MENU commands temporarily off.


ON MENU IBOX

You can define two independent rectangles with ON MENU IBOX and/or ON MENU
OBOX, either :
     - one IBOX and one OBOX
     - two IBOXes
     - two OBOXes


                            22.  PULLDOWN MENU


OPENW 0

Even if you don't need a window, you could 'OPENW 0' if you use a
pulldown menu. The top line (y-coordinates 0 to 18 in High resolution,
that's where your menu is) is now protected against accidental drawing.
After 'OPENW 0' 19 is always added to the y-coordinate, so with 'PLOT 0,0'
the point is actually drawn at (0,19).


Desk-submenu

The first submenu in a pulldown menu should be the Desk-submenu ('Desk'),
usually with the following lay-out :
     Info
     ------------
     Accessory 1
     Accessory 2
     (...)
If the user chooses the Info-item, you should show some information about
the program. The AES takes care of the accessory-items, you simply use
'1,2,3,4,5,6' in the corresponding DATA-line. If you use '-,-,-,-,-,-' the
user won't be able to choose an accessory from your program, but all
loaded accessories still occupy memory.


File-submenu

Most pulldown-menu's contain a File-submenu ('File') as the second
submenu. The following lay-out is more or less standard :
     New file       ^N
     Open file ...  ^O
     -----------------
     Close          ^C
     Save           ^S
     Save as ...    ^M
     Abort          ^A
     -----------------
     Quit           ^Q
With '...' you announce that further input from the user will be
requested. If at all possible, you should offer optional keyboard-
alternatives for the experienced user. With '^N' you remind the user of
the <Control> <N> alternative. The character with ASCII-code 7 is used as
the symbol for <Alternate>. By general agreement, the Quit-choice always
is the last item of the File-submenu.

By the way, never leave the last (rightmost) submenu without options, e.g.
during development of a program. There must be at least one option in the
last submenu, or it's reset-time again.


                               23.  WINDOWS


GFA-windows

You'll notice that this chapter is rather short. This reflects my
reservations about the use of windows. I know very few programs that use
windows sensibly. For these programs GEM-windows indeed are a blessing.
But most programs are better off without windows. GEM just slows the
screen-output down. Cover your TOS-screen with windows only if you really
need them.

GFA-Basic has four "easy" windows for not too complicated jobs. Draw an
imaginary cross on the screen. The intersection of the two lines is
determined by the coordinates in 'OPENW n,x,y'. If you show more than one
window on the screen, you should realize that resizing one window auto-
matically changes the size of the other three windows as well (remember
the cross?). Use the AES window-commands if you need independent windows.

The four GFA-windows reserve the top line for a pulldown menu. If you use
your own AES-windows, you should protect the top line yourself, e.g. with
'OPENW 0'.

A standard-method for the use of GFA-windows looks like this :
     TITLEW #1," title "      ! automatically centered
     INFOW #1,"information"   ! left justified
     OPENW 1                  ! or use FULLW #1
     CLEARW 1
     (...)
     CLOSEW 1
     CLOSEW 0
I don't know how to use '#' properly. The editor does not accept '#' in
'OPEN #1', you have to use 'OPENW 1'. If you use FULLW instead of OPENW,
you have to use 'FULLW #1'. In this case the '#' has to be used, or the
command doesn't work at all! The GFA-editor always inserts a '#' after
TITLEW and INFOW, even if you didn't type one. What the # is going on?


CLOSEW

If you have opened a window in your program, always use 'CLOSEW 0' before
returning to the editor. If you don't, you can't work normally in Direct
Mode. If you did forget, you can type 'CLOSEW 0' in Direct Mode and
everything works fine again.

If you use the AES window-commands, always call WIND_CLOSE(handle) before
WIND_DELETE(handle).


TITLEW

You can clear a title with :
     TITLEW #n," "
Don't use "" instead of " ", or you won't be able to move the window
afterwards!


CLEARW

After 'CLEARW #n' all visible areas of the window are cleared, without
activating the window. GFA uses WIND_UPDATE and WIND_GET for this command.
'CLEARW n' both clears and activates the window.


                             24.  AES-LIBRARY


ALERT

If you need an empty line in an Alert-box, use :
     ALERT,3,"...| |...",1,"...",k
Note the space between the two vertical rules.

GFA-Basic allows 4 lines of 30 characters (High/Medium rez) if you use
ALERT, but with FORM_ALERT you can use 5 lines. In both cases you can use
not more than 3 buttons, each at most 8 characters (High/Medium rez) wide:
     m$=" line 1 | line 2 | line 3 | line 4 "
     ALERT 3,m$,1," OK ",k
     '
     m$="[3][ line 1 | line 2 | line 3 | line 4 | line 5 ][ OK ]"
     k=FORM_ALERT(1,m$)

In Low resolution you can use only half the number of characters you use
in High/Medium resolution.

If some characters are not visible in a button, try broadening the Alert-
box by adding spaces to the widest text-line.

If you have pressed the left mouse-button on the very spot where an Alert-
button is about to appear, something goes wrong. GEM appears to remember
your last mouse-click, and erroneously assumes you pressed the button
after the Alert-box appeared. GEM only selects the button if the mouse-
click occurred in the exact area of the Alert-button. To avoid this
problem you should make sure the user has released the mouse-button before
you call the Alert-box :
     REPEAT
     UNTIL MOUSEK=0      ! wait until mouse released

By the way, the AES uses an 8K buffer to save the part of the screen where
the Alert-box appears. Ditto for a menu.


SHEL_GET and SHEL_PUT

GFA-Basic is run from a 'Shell-Program', usually the Desktop. In that case
the file DESKTOP.INF can be found in the Environment-Buffer. You can
examine this file by transferring it to a string :
     d$=STRING$(1024,0)
     r%=SHEL_GET(1024,d$)
PRINTing this string is much easier than using a disk-editor to examine
DESKTOP.INF.

After changing the string, you could put it back in the buffer with :
     r%=SHEL_PUT(1024,d$)
This way you could change the lay-out of the desktop. If you change the
string, you should know that the Desktop recognizes the end of DESKTOP.INF
by the byte &H1A. So don't forget to put CHR$(26) at the end. If you want
to save the new buffer, try :
     OPEN "O",#1,"\DESKTOP.INF"
     PRINT #1,LEFT$(d$,INSTR(d$,CHR$(26)))
     CLOSE #1






Is that all there is to tell about the AES-library? Certainly not, so at
this point you will probably be bitterly disappointed. I avoid the AES-
Library whenever I can. Anyway, this is a subject that is thoroughly
covered in most books about GFA-Basic 3.0. Everyone is entitled to his own
opinion about the usefulness of RSC-files and other exotic subjects.
Better still, write this chapter yourself. And the same to you too!


                           25.  GFAXPERT-FILES


Take your time to read this chapter carefully, before using the GFAXPERT-
Procedures or programs. The paragraph 'STANxxxx.LST' is essential reading.
Don't forget to read the 'small print' in the last paragraph.


GFAXPERT.DOC

You're reading it.


GFAXPERT.LIB

This folder (in GFAXPRT2.ARC for downloaders) contains a large collection
of Procedures in several LST-files. Each LST-file contains one or more
folded Procedures. Most Procedures are also listed in this text, or are at
least mentioned. I suggest you Llist all the LST-files with unfolded
Procedures for easy reference. You could also Llist all LST-files again
with folded Procedures, so you will be able to locate a Procedure quickly.

Always read the comment-lines (' ***) in a Procedure before using it. You
will find there if other Procedures are used, or Standard Globals (see
paragraph 'STANxxxx.LST'). Sometimes a Procedure returns a global
variable. Most variables are declared as LOCAL. And do read the relevant
chapter of this text before using a Procedure.

GFA has released a library of graphics- and sound-routines. I am curious
about the quality of these routines, but I certainly do not intend to pay
DM 148.- for the library. My advice would be to use the library
GFAXPERT.LIB and pay DM 148.- to me.


INLINE

The INLINE-folder (in GFAXPRT2.ARC for downloaders) contains INLINE-files
that you will have to load after Merging certain Procedures. This is
clearly indicated in such Procedures.


STANxxxx.LST

Before writing a program, I decide in which resolution the program will
run. Then I Merge the corresponding STANxxx.LST-file (in the folder
GFAXPERT.LIB) and use that as the standard framework for my program :
     STANHIGH.LST   - High resolution
     STANMED.LST    - Medium resolution
     STANLOW.LST    - Low resolution
     STANHIME.LST   - High or Medium resolution
     STANALL.LST    - all resolutions
After deleting the first two lines and entering the name of the program
(e.g. TEST.GFA), I Save the program as AAPROG.GFA in the Procedure-
library. In this folder I have a few LST-files ready for easy Merging of
Procedures into the program (AABLOCK1.LST, AABLOCK2.LST, etc.).

Before you continue, you should Llist the five STANxxxx.LST-files. Merge
STANHIGH.LST, unfold all Procedures, then Llist. In the other files you
could restrict unfolding to the Procedure Initio (and perhaps the
Procedures xxx.mode and Standard.xxx.colors). I'll wait until you have the
listings of the STAN-files in front of you...

Right, first I'll discuss STANHIGH.LST thoroughly. Later I'll point out
some important features in the other STAN-files. You will not become an
expert in structured programming immediately, but using the STAN-files
should help.

(1) The first line ('STANHIGH.LST') is there to remind you how to 'Save,A'
this file after you have changed it. Delete it if you are going to develop
a new program.

(2) Enter the name of your new program (e.g. TEST.GFA) and immediately
save the program as AAPROG.GFA in the Procedure-library.

(3) Word-variables are defined as the default.

(4) The Procedure Initio is called. In this Procedure the current
resolution is checked, and after that, a few important global variables
are defined (Standard Globals). The following Standard Globals are defined
(read the comments in the listing for more information) :
     high.res!           scrn.col.max        return$
                         scrn.lin.max        esc$
     default.path$                           help$
                         white               undo$
     physbase%           black
     logbase%                                interpreter$
                         on!                 run.only$
     scrn.x.max          off!                start.gfa$
     scrn.y.max                              start.prg$
                         bel$
     char.width
     char.height
Also, the Standard Array color.index() is created, although you'll only
need it for a few Procedures (e.g. Initio.sprite1).

(5) The Procedure Title.screen is not activated yet. You'll probably want
to change that Procedure.

(6) A normal <Break> should be possible while developing a program. In the
finished program you could activate the Procedure Break, or delete it. Be
very careful with <Break> if the program uses RESERVE or has changed the
address of the physical/logical screen.

(7) The main program usually is not much more than a list of Procedure-
calls, e.g. :
     @start.game
     @play.game
     @score
(8) Try to leave the program by calling the Procedure Exit. During
development it's more convenient to leave with 'EDIT'.

(9) Two Standard Functions are defined: Center$ for centering text and
Rev$ for PRINTing reverse. The last function uses VT52-codes, so use it on
the TOS-screen only.

(10) The Standard Procedure High.mode (called from Initio) checks the
current resolution and aborts with an appropriate message if the program
is run in the wrong resolution.

(11) The Standard Procedure Get.path (called from Initio) returns the
current path. Using the interpreter, GEMDOS returns the path of the
interpreter (e.g. 'A:\'), not of the running program! That's why I use
CHDRIVE + CHDIR in the shell-programs. In that case the Standard Global
default.path$ does contain the path of the running GFA-program. If you
develop the program, you should use CHDRIVE/CHDIR in Direct Mode if
necessary. I am not happy with this method, but I know no other solution
for GFA-programs. If I don't use this method, I always define the path in
the Initiation-part, e.g. :
     path$="A:\GAMES\"        ! where are the data-files?
Now another GFA-user only has to change the path and the program can find
the necessary files. For owners of the Run-Only interpreter you should
describe the proper configuration in a READ.ME-file. With compiled GFA-
programs there is no problem, because GEMDOS will return the path of the
running program.

(12) I like to begin every program with a title-screen. Change the
Standard Procedure Title.screen, or delete it if you don't like title-
screens in your programs.

(13) The Standard Procedure Return is used by Title.screen.

(14) The Standard Procedure Break can be deleted if you don't need it.
Don't use 'ON BREAK CONT' in your program, unless you have a very good
reason to do so. Note that I have made it possible to use <Break> the
normal way if the user chooses <CONT> while pressing the <Break>-
combination.

(15) The Standard Procedure Exit should always be used. This Procedure
tries to go back to one of the shell-programs. If that's impossible, the
Procedure decides to end with 'EDIT' or 'SYSTEM'. Is it possible to test
in a program if it is run by the interpreter or if it is a compiled
program? If the answer is yes, this Procedure could be improved.

(16) Other Procedures can be inserted after '*** Procedures ***'. Merge
Procedures from the library GFAXPERT.LIB (or your own library) here. I use
the following method :
     - New, so memory is clear
     - Merge relevant LST-file from library
     - choose (folded) Procedure and Write as block to AABLOCKx.LST
     - repeat previous steps for other Procedure(s)
     - Load AAPROG.GFA
     - Merge AABLOCKx.LST at appropriate position(s)
     - Save program (press <Return> in Fileselector)
Of course, you'll have to write a few Procedures from scratch. Before you
know it, you'll have reached The End. It's so easy to write a program in
GFA-Basic 3.0, that I actually enjoy programming.

(17) Debugging is perhaps less fun than programming. Merge the Procedure
Debug temporarily in your program if you need some help. And do save your
program regularly! Fall back to the program AAPROG.BAK if your latest
improvements were fatal. If you are completely satisfied, save the program
under its proper name (TEST.GFA). Also save a back-up on another disk,
just in case something terrible should happen to your original program.

(18) In STANALL.LST you'll notice in the Procedure Initio that I always
start with the default palette (Procedures Standard.med.colors and
Standard.low.colors). New Standard Globals in STANALL.LST are :
     red            med.res!
     green          low.res!
The Standard Array color.index() is very important in Medium or Low
resolution.

(19) In STANHIME.LST (my favourite) the only important difference is the
Procedure High.med.mode, where the current resolution is checked.

(20) In STANLOW.LST all 16 default-colours are now defined as Standard
Globals :
     white          blue           grey           l.purple
     black          d.blue         l.black        d.purple
     red            brown          l.blue         d.yellow
     green          d.green        bluegreen      l.yellow
With two new Standard Functions you can change the colour of PRINTed text
(Ink$) or the colour of the background (Paper$). Both functions work on
the TOS-screen only. The current resolution is checked in the Procedure
Low.mode.

(21) Nothing new in STANMED.LST, except the Procedure Med.mode to check
the resolution.

Perhaps you find all this talk about a "standard" program-structure very
boring. If you write a program, why care about structure? Because it's
much easier to change a structured program, especially if you didn't write
the program yourself. Change an unstructured program, and you're going to
be surprised by some (hidden) unwanted side-effects. Make other users
happy, spread your beautiful programs only if they are structured and well
commented. Do spread the (listable) source of your program, so other users
can learn from you. And don't be insulted if others improve your program.
I certainly will not be insulted if you send me your own thoughts about
structured programming in GFA-Basic 3.0.



START

In the START-folder (in GFAXPRT2.ARC for downloaders) you will find the
following programs :
     START.GFA      - High or Medium resolution
     STARTLOW.GFA   - Low resolution
     GFASTART.GFA   - all resolutions

I use two different disks for my GFA-programs. One for programs that run
in High and/or Medium resolution (save the desktop in Medium resolution!).
And one for programs that run in Low resolution.

START.GFA and STARTLOW.GFA are used as a kind of shell to run the GFA-
programs on these disks. Not a true shell, but it "feels" like all GFA-
programs are run from START.GFA and STARTLOW.GFA. I start a GFA-session
by double-clicking the shell-program on the desktop ('GFA' has been
installed as application for GFABASIC.PRG).

All my programs try to CHAIN one of the shell-programs when the user exits
the program. Two important remarks if you decide to use these shell-
programs :
     - vertical frequency is switched to 60 Hz in Medium or Low resolu-
       tion; not a good idea if you use a TV through a modulator!
     - Write Verify Test is switched off
If you like, you can activate the check for a boot-virus in the shell-
programs. The shell-program and GFABASIC.PRG (or GFABASRO.PRG) should be
in the main directory!

GFASTART.PRG is used in the same way with compiled GFA-programs. All my
compiled GFA-programs try to CHAIN this shell-program when exiting. The
source for this program is GFASTART.GFA. Compile this as GFASTART.PRG and
put it in the main directory.

All three START-programs contain plenty comments, so you should be able to
understand how the programs work by studying the listings. The shell-
programs certainly can be improved, I'm not yet satisfied with the current
programs.


small print

Read this paragraph carefully, before using the GFAXPERT-files. The files
are not Public Domain!

You are free to use and change all GFAXPERT-files, but only for personal
use. Certainly not for commercial use.

You are invited to copy the original GFAXPERT-disk or the GFAXPRTx.ARC-
files and give these to your friends. But you are not allowed to change
anything on the disk or in the files. If you feel the urge to change
something, don't do it, but write to me (read the chapter 'EPILOGUE').

You are not allowed to sell (files from) the GFAXPERT-disk or one of the
GFAXPRTx.ARC-files. The disk GFAXPERT may only be sold by so-called Public
Domain Clubs if they have my written permission to do so. BBS's are free
to make the original GFAXPRTx.ARC-files available for downloading.

Any part from the text GFAXPERT.DOC or the Procedure-library GFAXPERT.LIB
may be quoted in newsletters or magazines, if accompanied by a reference
like :
      from GFAXPERT (2nd ed.) by Han Kempen

I cannot be held responsible for any damage that may result from running a
GFAXPERT-program, using a Procedure from the library GFAXPERT.LIB, or
using information from this text.


(c) Han Kempen, 3 July 1990


                                 EPILOGUE


Well, that's all folks. I'm quite certain there are still a few bugs to be
found in this text and in the Procedure-Library GFAXPERT.LIB. By now you
should have become an expert in GFA-Basic 3.0, so you will be able to spot
them bugs immediately. Please let me know if you find one.

Perhaps you still have some unanswered questions about GFA-Basic. Or an
answer to one of my own questions in this text. Or some neat Procedures.
Or a brilliant program. I would appreciate it very much if you would send
your letter and/or disk to :

     Han Kempen
     Rubensstraat 12
     7741 AR Coevorden
     the Netherlands

Do share your ideas, Procedures and programs with others, starting with
me. Consider it a small payment for the GFAXPERT-files. Thanks.






Wishing you many happy hours with GFA-Basic 3.0,


Han Kempen


                                  INDEX



                       (#) = Procedure or Function


\ .....................................  29
" .....................................  41
1st Word Plus .........................  62
40-folder limit .......................  66

abbreviated commands ..................  12
accessory .............................  25,101
ACHAR .................................  96
ACLIP .................................  99
After$ (#) ............................  32
AFTER .................................  82
ALERT ................................. 106
application ...........................   9
ARECT .................................  88
ASCII-code ............................  33,34,36,37
Ascii.qsort (#) .......................  27
ATEXT .................................  96
attribute .............................  53
AUTO ..................................   9

BCHG ..................................  30
BCLR ..................................  29
Before$ (#) ...........................  32
Bezier-curve ..........................  92
BGET ..................................  62
BIOS  4 (Rwabs) .......................  59
BIOS  7 (Getbpb) ......................  56,60
BIOS  9 (Mediach) .....................  60
BIOS 10 (Drvmap) ......................  51
BIOS 11 (Kbshift) .....................  36
bit-mask ..............................  29
Blitter (#) ...........................  99
BLOAD .................................  61
Block.dimmer (#) ......................  91
Boolean ...............................  17
boot ..................................   9,61
BPB ...................................  56
BPUT ..................................  62
break .................................  10
Break (#) ............................. 110
BSAVE .................................  61
BSET ..................................  30,79
bug (GFA) .............................  12,20,24,25,31,32,36,42,80,83,
                                                        84,92,96,97,101
bug (TOS) .............................  25,35,55,56,63,64,66,70,95,102

calculations ..........................  79
Caps (#) ..............................  39
CapsLock ..............................  38
CARD ..................................  31
CHAIN .................................  83
Change.font (#) .......................  44
Change.midi.buffer (#) ................  67
Change.palette (#) ....................  85
characters ............................  16,34
CHDIR .................................  51,110
CLEAR .................................  19
CLEARW ................................ 105
CLIP ..................................  92
CLOSEW ................................ 104
cluster ...............................  58
Coldstart (#) .........................   9
color .................................  40
Color.cycle (#) .......................  86
correlation ...........................  31
COSQ ..................................  30
CURVE .................................  92
Cut and Paste .........................  13
Cycle.once (#) ........................  87

DATE$ .................................  22
Day.of.week (#) .......................  22
Debug (#) .............................  19,111
DEFFILL ...............................  87
DEFLINE ...............................  89
DEFLIST ...............................  15
DEFMARK ...............................  87
DEFMOUSE ..............................  72
DEFTEXT ...............................  89
DEFWRD ................................  17
Degas-Pictures ........................  97
Degas.screendump (#) ..................  46
DELAY .................................  83
Desk-submenu .......................... 103
DESKTOP.INF ........................... 106
DFREE .................................  56,58
Digital$ (#) ..........................  93
DIM ...................................  19
Dim.colors (#) ........................  86
DIR$() ................................  50
DIR ...................................  51
Direct mode ...........................  15
disk format ...........................  55
disk-swap .............................  60
Do.sound (#) ..........................  76
DRAW ..................................  91
DTA-buffer ............................  52
DUMP ..................................  19

Editor ................................  71
EQV ...................................  31
ERASE .................................  19,24
ERROR .................................  82
EVERY .................................  82
EXEC ..................................  24,83
EXIST .................................  54
Exit (#) .............................. 110

fade-over .............................  99
Fastprint (#) .........................  41
FAT ...................................  58
FDC ...................................  55
FGETDTA ...............................  52
File Allocation Table .................  58
File.copy (#) .........................  55
File-submenu .......................... 103
FILES .................................  51
FILESELECT ............................  63
Fileselect (#) ........................  64
Fileselector ..........................  63,71
floating point ........................  18
Floppy Write Test .....................  50
Folded Procedures .....................  13
font ..................................  43,89
Font.8x16 (#) .........................  43
Font.8x8 (#) ..........................  43
FONTKIT ...............................  44
FOR ... NEXT ..........................  79
Force.mediach (#) .....................  60
FORM_ALERT ............................ 106
FSETDTA ...............................  52
FSFIRST ...............................  52
FSNEXT ................................  52
Full.fill (#) .........................  88
FULLW ................................. 104
FUNCTION ..............................  19

GEMDOS 17 (Cprnos) ....................  45
GEMDOS 25 (Dgetdrv) ...................  50
GEMDOS 48 (Sversion) ..................  10
GEMDOS 54 (Dfree) .....................  56
GEMDOS 67 (Fattrb) ....................  53
GET ...................................  96
Get.path (#) .......................... 110
GFA-windows ........................... 104
GFAXPERT.DOC ..........................   7,108
GFAXPERT.LIB ..........................   7,108
GOSUB .................................  82
GOTO ..................................  82
GRAPHMODE .............................  90

HARDCOPY ..............................  45
harddisk ..............................  51,55,58,59
High.screendump.epson (#) .............  45
High.screendump.star24 (#) ............  45
HLINE .................................  96

IBOX .................................. 102
IF ... ENDIF ..........................  78
INFOW ................................. 194
Initio (#) ............................ 109
Initio.fill1 (#) ......................  88
Initio.high.fill1 (#) .................  87
Initio.keyget (#) .....................  36
Initio.logical.screen (#) .............  42
Initio.mouse1 (#) .....................  72
Initio.printer (#) ....................  47
Initio.sound (#) ......................  75
Initio.sprite1 (#) ....................  93
Initio.text.array (#) .................  62
Ink$ (#) ..............................  40
INKEY$ ................................  33
INLINE ................................  24,108
INP ...................................  62,67,70
INPAUX$ ...............................  70
INPMID$ ...............................  67
INPUT .................................  34,62
INPUT$ ................................  35
Insert-mode ...........................  15
INSTR .................................  32
INT{} .................................  23
integer ...............................  18
Intel.word (#) ........................  31
interleave ............................  57
Invert.block (#) ......................  91

joystick ..............................  74

Key.click (#) .........................  38
Key.repeat (#) ........................  39
keyboard ..............................  37
keyboard-buffer .......................  33
Keyboard.version (#) ..................  37
KEYDEF ................................  37
KEYGET ................................  35
KEYLOOK ...............................  36
KEYPAD ................................  37
KEYPRESS ..............................  37
KEYTEST ...............................  35
KILL ..................................  54

Line-A ................................  95
LINE INPUT ............................  35,62
Llist .................................  14
Load ..................................  13
LOCATE ................................  41
LOF ...................................  54
LOG ...................................  30
logical screen ........................  42
loops .................................  80,119
LSET ..................................  32

Make.high.fill (#) ....................  88
Make.mouse (#) ........................  73
Make.palette.string (#) ...............  85
Make.sprite (#) .......................  94
MALLOC ................................  25
MAX ...................................  31,78
Max.array (#) .........................  31
memory ................................  23,24,25
MENU() ................................ 101
Midi-buffer ...........................  67
Midi-commands .........................  67
Midi.monitor (#) ......................  68
MIN ...................................  78
MOD ...................................  29
monitor ...............................  10
MOUSE .................................  71
MS-DOS disk ...........................  58

NAME ..................................  54
Neochrome-Pictures ....................  98
New.med.colors (#) ....................  85
Normal.font (#) .......................  44
NOT ...................................  81

OBOX .................................. 102
ON BREAK GOSUB ........................  82
ON MENU BUTTON ........................ 101
ON MENU IBOX .......................... 102
OPENW ................................. 104
OPENW 0 ............................... 103
Operating System ......................  10
OUT ...................................  40,62
Overwrite-mode ........................  15

palette ...............................  84,111
Palette.box (#) .......................  86
Paper$ (#) ............................  40
Parse.filename (#) ....................  65
parser ................................  32
PCIRCLE ...............................  92
physical screen .......................  42
Play.midi (#) .........................  68
PLOT ..................................  91
point-commands ........................  14
PRED ..................................  29
PRINT .................................  40
Print.stopwatch (#) ...................  21
PRINT TAB .............................  42
printer-commands ......................  47
printer-driver ........................  14
printer-parameters ....................  45
Printer.ready (#) .....................  45
PUT ...................................  96

QSORT .................................  26

RAM ...................................  23
RAM-disk ..............................  50
READ ..................................  20
RECALL ................................  62
Record.midi (#) .......................  67
RESERVE ...............................  23
reset .................................   9,50
RESTORE ...............................  20
Restore.palette (#) ...................  85
Restore.physical.screen (#) ...........  43
Return (#) ............................ 110
reverse ...............................  41,84
Rgb.value (#) .........................  85
right justification ...................  32
RS232-buffer ..........................  70
RSET ..................................  32
Rubber.line (#) .......................  90

samples ...............................  76
Save ..................................  14
Save,A ................................  14
Save.palette (#) ......................  85
scan-code .............................  33,36,37,38
scrap-library .........................  83
Screen.dimmer (#) .....................  91
Screendump (#) ........................  45
Scroll.text.up (#) ....................  99
Scroll.up (#) .........................  98
sectors ...............................  59
SELECT ................................  78
serial number .........................  57
SETCOLOR ..............................  84
SETMOUSE ..............................  71
SHEL_GET .............................. 106
SHEL_PUT .............................. 106
shell-program ......................... 112
SHL ...................................  79
Show.degas (#) ........................  97
Show.text.page (#) ....................  63
Shuffle (#) ...........................  20
SINQ ..................................  30
SOUND .................................  75
Soundmachine ..........................  77
special characters ....................  16
speech ................................  77
SPRITE ................................  93
SSORT .................................  26
Standard ..............................   7
Standard Array ........................ 109,111
Standard Functions .................... 110,111
Standard Globals ...................... 109,111
STANxxxx.LST .......................... 108
START ................................. 112
start-up ..............................   9
Step Rate .............................  50
STICK .................................  74
Stopwatch (#) .........................  21
STORE .................................  62
STRIG .................................  74
String.index.qsort (#) ................  28
SUCC ..................................  29
supervisor mode .......................  23
SWAP ..................................  20,31
Swap.screen (#) .......................  43
syntax ................................  12
system-font ...........................  43,89

Tab ...................................  13,41
TAB ...................................  42
TEXT ..................................  92
text-array ............................  62
Text.at (#) ...........................  92
TIME$ .................................  21
Time (#) ..............................  21
TIMER .................................  21
Title.screen (#) ...................... 110
TITLEW ................................ 104,105
TOS ...................................  10
TOS-screen ............................  40
TOUCH .................................  54
twisted format ........................  57
TYPE ..................................  20

VAR ...................................  18
variable type .........................  17
VDISYS 38 (vqt_attributes) ............  89
VQT_EXTENT ............................  95
VSETCOLOR .............................  84
VSYNC .................................  98
VT52 ..................................  40

Warmstart (#) .........................   9
WAVE ..................................  75
WIND_CLOSE ............................ 104
word ..................................  17,31
WORD ..................................  23,59
write-protect .........................  60

XBIOS  0 (Initmous) ...................  71
XBIOS  5 (Setscreen) ..................  42
XBIOS  6 (Setpalette) .................  85,97
XBIOS  7 (Setcolor) ...................  84
XBIOS  8 (Floprd) .....................  60
XBIOS 10 (Flopfmt) ....................  56
XBIOS 15 (Rsconf) .....................  70
XBIOS 16 (Keytbl) .....................  37,38
XBIOS 18 (Protobt) ....................  57
XBIOS 19 (Flopver) ....................  56
XBIOS 32 (Dosound) ....................  75
XBIOS 33 (Setprt) .....................  45
XBIOS 36 (Prtblk) .....................  47
XBIOS 64 (Blitmode) ...................  99